From 24637cd3776cda5fd0a919ba9343ba86d82d3e04 Mon Sep 17 00:00:00 2001
From: Laurent Bercot Download
-
- If your application has trouble handling unknown -children, consider using an ftrigrd service. (And fix your application!) -
-@@ -61,8 +56,8 @@ for instance, illustrate how to use the ftrigr library.
-ftrigr_t a = FTRIGR_ZERO ; +ftrigr 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 an ftrigrd service listening on
-path.
ftrigr_startf starts a session with an ftrigrd process as a child
(which is the simplest usage).
-a is an ftrigr_t structure that must be declared in the stack and
-initialized to FTRIGR_ZERO.
+a is an ftrigr structure that can be declared in the stack and
+must be 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. @@ -135,8 +127,8 @@ 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. +several distinct ftrigr structures and calling +ftrigr_startf more than once. However, this is useless, since one single session can handle virtually as many concurrent fifodirs as your application needs.
@@ -156,8 +148,10 @@ ftrigr_end(&a) ; char const *path = "/var/lib/myservice/fifodir" ; char const *re = "a.*b|c*d" ; uint32_t options = 0 ; +uint32_t timeout = 60000 ; +uint32_t id ; -uint16_t id = ftrigr_subscribe (&a, path, re, options, &deadline, &stamp) ; +int r = ftrigr_subscribe(&a, &id, options, timeout, path, re, options, &deadline, &stamp) ;@@ -165,7 +159,9 @@ uint16_t id = ftrigr_subscribe (&a, path, re, options, &deadline, &s 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. +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 @@ -173,8 +169,16 @@ 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. + If timeout is nonzero, it represents a number of milliseconds; +after this delay, the daemon will automatically unsubscribe from +path and report an ETIMEDOUT error to the client. It is not +advised to use a nonzero timeout along with the FTRIGR_REPEAT option. +
+ ++ If it fails, ftrigr_subscribe() returns 0 and sets errno. If +it succeeds, it returns 1 and stores a number identifying the subscription +into id.
@@ -188,26 +192,29 @@ and events can be sent without the risk of a race condition.
-uint16_t list[1] ;
+uint32_t list[1] = { id } ;
unsigned int n = 1 ;
-char trigger ;
-list[0] = id ;
+ftrigr_string fs ;
// r = ftrigr_wait_and(&a, list, n, &deadline, &stamp) ;
-r = ftrigr_wait_or(&a, list, n, &deadline, &stamp, &trigger) ;
+r = ftrigr_wait_or(&a, list, n, &deadline, &stamp, &fs) ;
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.
+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. +an event; and fs is the list of events that were received +since the subscription and matched the re regular expression. +fs.s is a char * pointing to the (not null-terminated) +string of events, and fs.len is its length.
-int ftrigr_fd (ftrigr_t const *a) +int ftrigr_fd (ftrigr const *a)
@@ -227,30 +234,19 @@ int ftrigr_fd (ftrigr_t const *a)
-int ftrigr_updateb (ftrigr_t *a) +int ftrigr_update (ftrigr *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_updateb returns, -genalloc_s(uint16_t, &a->list) points to an array of -genalloc_len(uint16_t, &a->list) 16-bit unsigned -integers. Those integers are ids waiting to be passed to -ftrigr_check or ftrigr_checksa. -The number of ids already acknowledged is stored in -a->head, so the first unacknowledged id is -genalloc_s(uint16_t, &a->list)[a->head]. +s6-ftrigrd daemon. It returns -1 (and sets +errno) if an error occurs, 0 if there were no events, and 1 if events +were received.
-int ftrigr_check (ftrigr_t *a, uint16_t id, char *what) +int ftrigr_peek (ftrigr *a, uint32_t id, ftrigr_string *fs)
@@ -263,49 +259,39 @@ call to ftrigr_updateb(). number may have been transmitted from s6-ftrigrd.
-int ftrigr_checksa (ftrigr_t *a, uint16_t id, stralloc *what) +void ftrigr_ack (ftrigr *a, uint32_t id)
- Checks whether an event happened to id. Use after a -call to ftrigr_update(), as an alternative to ftrigr_check(). + Resets the stored string of events. The next invocation of +ftrigr_peek() will only show new events, if any.
--void ftrigr_ack (ftrigr_t *a, size_t n) +int ftrigr_release (ftrigr *a, uint32_t id)
- Acknowledges reading n ids from the id list updated by -ftrigr_updateb. + Frees the resources used by subscription id. Use this +after getting an event from a subscription done without the +FTRIGR_REPEAT flag and reading its results, if you want to +keep the session open and perform more subscriptions.
--int ftrigr_update (ftrigr_t *a) --
- Acknowledges all the pending ids (i.e. clears the stored id list) -then calls ftrigr_updateb(). + If subscription id was given the FTRIGR_REPEAT flag, +use ftrigr_unsubscribe() instead. If you're not going +to perform other subscriptions, ftrigr_end() will +free all the resources without you needing to call +ftrigr_release() first.