s6
Software
www.skarnet.org
The s6-ftrigrd program
s6-ftrigrd is a helper program that manages a set of subscriptions to fifodirs as well
as regular expressions on events. It takes orders from its client program that controls
it via the ftrigr library, and notifies it when desired
events happen.
Interface
s6-ftrigrd is not meant to be called directly.
- If the client program uses ftrigr_startf(), it spawns an instance of
s6-ftrigrd as a child. s6-ftrigrd's stdin is a pipe reading from the client; its
stdout is a pipe writing to the client; its stderr is the same as the client's; and
there's an additional pipe from s6-ftrigrd to the client, used for asynchronous
notifications.
- If the client program uses ftrigr_start(), then it tries to connect
to a Unix domain socket. A ftrigrd service should be listening to that
socket, i.e. a Unix domain superserver such as
s6-ipcserver
spawning a s6-ftrigrd program on every connection. Then a s6-ftrigrd instance is created
for the client: its stdin and stdout are the socket, its stderr is normally logged
by the service's logger, and there's also an additional pipe from s6-ftrigrd to the
client, used for asynchronous notifications. Such a pipe can exist thanks to some
Unix black magic (the
libancillary,
if you must know).
- When the client uses ftrigr_end(), or closes s6-ftrigrd's stdin in
any way, s6-ftrigrd exits 0.
s6-ftrigrd handles the grunt work of creating fifos in a
fifodir for a subscriber. It also wakes up on every
event, and compares the chain of events it received on a given fifodir with the
client-provided regexp. If the chain of events matches the regexp, it notifies
the client.
Notes
The connection management between the client and s6-ftrigrd is entirely done
by the skaclient
library. The protocol uses netstrings
for message boundaries.
s6-ftrigrd is entirely asynchronous. It stores unread notifications into heap
memory; it can grow in size if there are a lot of events and the client fails
to read them. To avoid uncontrolled growth, make sure your client calls
ftrigr_update() as soon as ftrigr_fd() becomes readable.