From 87c5b2118efcee65eeda3f743d081ea9c2b866d9 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 15 Jan 2015 20:14:44 +0000 Subject: Move Unix domain utilities and access control utilites, as well as the accessrules library, from s6-networking to here --- doc/libs6/ftrigr.html | 268 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 doc/libs6/ftrigr.html (limited to 'doc/libs6/ftrigr.html') diff --git a/doc/libs6/ftrigr.html b/doc/libs6/ftrigr.html new file mode 100644 index 0000000..2c9bf88 --- /dev/null +++ b/doc/libs6/ftrigr.html @@ -0,0 +1,268 @@ + + + + + s6: the ftrigr library interface + + + + + + +

+libs6
+s6
+Software
+skarnet.org +

+ +

The ftrigr library interface

+ +

+ The ftrigr library provides an API for listeners, i.e. +programs that want to subscribe to fifodirs and be instantly +notified when the proper sequence of events happens. +

+ +

Programming

+ +

+ Check the s6/ftrigr.h header for the +exact function prototypes. +

+ +

+ Make sure your application is not disturbed by children it doesn't +know it has. This means paying some attention to the SIGCHLD handler, +if any, and to the way you perform waitpid()s. The best +practice is to use a +self-pipe +to handle SIGCHLD (as well as other signals the application needs to trap), +and to always use wait_nohang() to reap children, +simply ignoring pids you don't know. +

+ +

+ If your (badly programmed) application has trouble handling unknown +children, consider using a ftrigrd service. +

+ +

A programming example

+ +

+ The src/pipe-tools/s6-ftrig-listen1.c and +src/supervision/s6-svwait.c files in the s6 package, +for instance, illustrate how to use the ftrigr library. +

+ + +

Synchronous functions with a specified maximum execution time

+ + + + +

Starting and ending a session

+ +
+ftrigr_t a = FTRIGR_ZERO ;
+tain_t deadline, stamp ;
+
+tain_now(&stamp) ;
+tain_addsec(&deadline, &stamp, 2)
+
+// char const *path = FTRIGR_IPCPATH ;
+// ftrigr_start(&a, path, &deadline, &stamp) ;
+ftrigr_startf(&a, &deadline, &stamp) ;
+
+ +

+ftrigr_start starts a session with a ftrigrd service listening on +path.
+ftrigr_startf starts a session with a ftrigrd process as a child +(which is the simplest usage).
+a is a ftrigr_t structure that must be declared in the stack and +initialized to FTRIGR_ZERO. +stamp must be an accurate enough timestamp.
+If the session initialization fails, the function returns 0 and errno is set; +else the function returns 1. +

+

+If the absolute time deadline is reached and the function +has not returned yet, it immediately returns 0 with errno set to ETIMEDOUT. + +Only local interprocess communications are involved; unless your system is +heavily overloaded, the function should return near-instantly. One or two +seconds of delay between stamp and deadline should be +enough: if the function takes more than that to return, then there is a +problem with the underlying processes. +

+ +

+ You can have more than one session open in parallel, by declaring +several distinct ftrigr_t structures and calling +ftrigr_startf (or ftrigr_start) more than once. +However, this is useless, since one single session can handle +virtually as many concurrent fifodirs as your application needs. +

+ +
+ftrigr_end(&a) ;
+
+ +

+ftrigr_end frees all the resources used by the session. The +a structure is then reusable for another session. +

+ +

Subscribing to a fifodir

+ +
+char const *path = "/var/lib/myservice/fifodir" ;
+char const *re = "a.*b|c*d" ;
+uint32 options = 0 ;
+
+uint16 id = ftrigr_subscribe (&a, path, re, options, &deadline, &stamp) ;
+
+ +

+ftrigr_subscribe instructs the +s6-ftrigrd daemon, related to the open +session represented by the a structure, to subscribe to the +path fifodir, and to notify the application when it receives +a series of events that matches the re regexp. +options can be 0 or FTRIGR_REPEAT. If it is 0, the daemon will +automatically unsubscribe from path once re has been +matched by a series of events. If it is FTRIGR_REPEAT, it will remain +subscribed until told otherwise. +

+ +

+ ftrigr_subscribe() returns 0 and sets errno in case of failure, or +a nonzero 16-bit number identifying the subscription in case of success. +

+ +

+ftrigr_subscribe should return near-instantly, but if +deadline is reached, it will return 0 ETIMEDOUT. If +ftrigr_subscribe returns successfully, then the +s6-ftrigrd daemon is guaranteed to be listening on path, +and events can be sent without the risk of a race condition. +

+ +

Synchronously waiting for events

+ +
+uint16 list[1] ;
+unsigned int n = 1 ;
+char trigger ;
+list[0] = id ;
+
+// r = ftrigr_wait_and(&a, list, n, &deadline) ;
+r = ftrigr_wait_or(&a, list, n, &deadline, &trigger) ;
+
+ +

+ ftrigr_wait_and() waits for all the n fifodirs +whose ids are listed in list to receive an event. It returns -1 +in case of error or timeout, or a non-negative integer in case of success.
+ ftrigr_wait_or() waits for one of the n fifodirs +whose ids are listed in list to receive an event. It returns -1 +in case of error or timeout; if it succeeds, the return value is the +position in list, starting at 0, of the identifier that received +an event; and trigger is set to the character that triggered that +event, i.e. the last character of a sequence that matched the regular +expression re used in the subscription. +

+ +

Asynchronously waiting for events

+ +

+ (from now on, the functions are listed with their prototypes instead +of usage examples.) +

+ +
+int ftrigr_fd (ftrigr_t const *a)
+
+ +

+ Returns a file descriptor to select on for reading. Do not +read() it though. +

+ +
+int ftrigr_update (ftrigr_t *a)
+
+ +

+ Call this function whenever the fd checks readability: it will +update a's internal structures with information from the +s6-ftrigrd daemon. It returns -1 if an error +occurs; in case of success, it returns the number of identifiers for +which something happened. +

+ +

+ When ftrigr_update returns, +genalloc_s(uint16, &a->list) points to an array of +genalloc_len(uint16, &a->list) 16-bit unsigned +integers. Those integers are ids waiting to be passed to +ftrigr_check. +

+ +
+int ftrigr_check (ftrigr_t *a, uint16 id, char *what)
+
+ +

+ Checks whether an event happened to id. Use after a +call to ftrigr_update(). +

+ + + + + -- cgit v1.2.3