From 24637cd3776cda5fd0a919ba9343ba86d82d3e04 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Wed, 18 Mar 2026 01:57:01 +0000
Subject:  More fixes, ftrigr_string addition, doc update

---
 doc/libs6/ftrigr.html     | 132 +++++++++++++++++++++-------------------------
 doc/libs6/s6-ftrigrd.html |  37 ++++++-------
 2 files changed, 76 insertions(+), 93 deletions(-)

(limited to 'doc/libs6')

diff --git a/doc/libs6/ftrigr.html b/doc/libs6/ftrigr.html
index 052d7bf..a8cf98b 100644
--- a/doc/libs6/ftrigr.html
+++ b/doc/libs6/ftrigr.html
@@ -43,11 +43,6 @@ and to <em>always</em> use <tt>wait_nohang()</tt> to reap children,
 simply ignoring pids you don't know.
 </p>
 
-<p>
- If your application has trouble handling unknown
-children, consider using an ftrigrd service. (And fix your application!)
-</p>
-
 <h3> A programming example </h3>
 
 <p>
@@ -61,8 +56,8 @@ for instance, illustrate how to use the ftrigr library.
 </a>
 
 <ul>
- <li> Synchronous functions take a <tt>tain_t const *</tt>
-(<em>deadline</em>) parameter and a <tt>tain_t *</tt> (<em>stamp</em>)
+ <li> Synchronous functions take a <tt>tain const *</tt>
+(<em>deadline</em>) parameter and a <tt>tain *</tt> (<em>stamp</em>)
 parameter. Those are pointers to tain_t structures containing absolute times;
 the former represents a deadline (in most cases, this time will be in the
 future) and the latter must be an accurate enough timestamp. These
@@ -100,28 +95,25 @@ control on. </li>
 <h3> Starting and ending a session </h3>
 
 <pre>
-ftrigr_t a = FTRIGR_ZERO ;
+ftrigr a = FTRIGR_ZERO ;
 tain_t deadline, stamp ;
 
 tain_now(&amp;stamp) ;
 tain_addsec(&amp;deadline, &amp;stamp, 2)
 
-// char const *path = FTRIGR_IPCPATH ;
-// ftrigr_start(&amp;a, path, &amp;deadline, &amp;stamp) ;
 ftrigr_startf(&amp;a, &amp;deadline, &amp;stamp) ;
 </pre>
 
 <p>
-<tt>ftrigr_start</tt> starts a session with an ftrigrd service listening on
-<em>path</em>. <br />
 <tt>ftrigr_startf</tt> starts a session with an ftrigrd process as a child
 (which is the simplest usage). <br />
-<tt>a</tt> is an ftrigr_t structure that must be declared in the stack and
-initialized to FTRIGR_ZERO.
+<tt>a</tt> is an ftrigr structure that can be declared in the stack and
+must be initialized to FTRIGR_ZERO.
 <tt>stamp</tt> must be an accurate enough timestamp. <br />
 If the session initialization fails, the function returns 0 and errno is set;
 else the function returns 1.
 </p>
+
 <p>
 If the absolute time <tt>deadline</tt> 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.
 
 <p>
  You can have more than one session open in parallel, by declaring
-several distinct <tt>ftrigr_t</tt> structures and calling
-<tt>ftrigr_startf</tt> (or <tt>ftrigr_start</tt>) more than once.
+several distinct <tt>ftrigr</tt> structures and calling
+<tt>ftrigr_startf</tt> more than once.
 However, this is useless, since one single session can handle
 virtually as many concurrent fifodirs as your application needs.
 </p>
@@ -156,8 +148,10 @@ ftrigr_end(&amp;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 (&amp;a, path, re, options, &amp;deadline, &amp;stamp) ;
+int r = ftrigr_subscribe(&amp;a, &amp;id, options, timeout, path, re, options, &amp;deadline, &amp;stamp) ;
 </pre>
 
 <p>
@@ -165,7 +159,9 @@ uint16_t id = ftrigr_subscribe (&amp;a, path, re, options, &amp;deadline, &amp;s
 <a href="s6-ftrigrd.html">s6-ftrigrd daemon</a>, related to the open
 session represented by the <tt>a</tt> structure, to subscribe to the
 <tt>path</tt> fifodir, and to notify the application when it receives
-a series of events that matches the <tt>re</tt> regexp.
+a series of events that matches the <tt>re</tt> regexp. </p>
+
+<p>
 <tt>options</tt> can be 0 or FTRIGR_REPEAT. If it is 0, the daemon will
 automatically unsubscribe from <tt>path</tt> once <tt>re</tt> has been
 matched by a series of events. If it is FTRIGR_REPEAT, it will remain
@@ -173,8 +169,16 @@ subscribed until told otherwise.
 </p>
 
 <p>
- <tt>ftrigr_subscribe()</tt> returns 0 and sets errno in case of failure, or
-a nonzero 16-bit number identifying the subscription in case of success.
+ If <tt>timeout</tt> is nonzero, it represents a number of milliseconds;
+after this delay, the daemon will automatically unsubscribe from
+<tt>path</tt> and report an ETIMEDOUT error to the client. It is not
+advised to use a nonzero timeout along with the FTRIGR_REPEAT option.
+</p>
+
+<p>
+ If it fails, <tt>ftrigr_subscribe()</tt> returns 0 and sets errno. If
+it succeeds, it returns 1 and stores a number identifying the subscription
+into <tt>id</tt>.
 </p>
 
 <p>
@@ -188,26 +192,29 @@ and events can be sent without the risk of a race condition.
 <h3> Synchronously waiting for events </h3>
 
 <pre>
-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(&amp;a, list, n, &amp;deadline, &amp;stamp) ;
-r = ftrigr_wait_or(&amp;a, list, n, &amp;deadline, &amp;stamp, &amp;trigger) ;
+r = ftrigr_wait_or(&amp;a, list, n, &amp;deadline, &amp;stamp, &amp;fs) ;
 </pre>
 
 <p>
  <tt>ftrigr_wait_and()</tt> waits for <em>all</em> the <tt>n</tt> fifodirs
 whose ids are listed in <tt>list</tt> to receive an event. It returns -1
-in case of error or timeout, or a non-negative integer in case of success. <br />
+in case of error or timeout, or a non-negative integer in case of success.
+</p>
+
+<p>
  <tt>ftrigr_wait_or()</tt> waits for <em>one</em> of the <tt>n</tt> fifodirs
 whose ids are listed in <tt>list</tt> to receive an event. It returns -1
 in case of error or timeout; if it succeeds, the return value is the
 position in <tt>list</tt>, starting at 0, of the identifier that received
-an event; and <tt>trigger</tt> is set to the character that triggered that
-event, i.e. the last character of a sequence that matched the regular
-expression <tt>re</tt> used in the subscription.
+an event; and <tt>fs</tt> is the list of events that were received
+since the subscription and matched the <tt>re</tt> regular expression.
+<tt>fs.s</tt> is a <tt>char *</tt> pointing to the (not null-terminated)
+string of events, and <tt>fs.len</tt> is its length.
 </p>
 
 <h3> Asynchronously waiting for events </h3>
@@ -218,7 +225,7 @@ of usage examples.) </em>
 </p>
 
 <pre>
-int ftrigr_fd (ftrigr_t const *a)
+int ftrigr_fd (ftrigr const *a)
 </pre>
 
 <p>
@@ -227,30 +234,19 @@ int ftrigr_fd (ftrigr_t const *a)
 </p>
 
 <pre>
-int ftrigr_updateb (ftrigr_t *a)
+int ftrigr_update (ftrigr *a)
 </pre>
 
 <p>
  Call this function whenever the fd checks readability: it will
 update <em>a</em>'s internal structures with information from the
-<a href="s6-ftrigrd.html">s6-ftrigrd</a> daemon. It returns -1 if an error
-occurs; in case of success, it returns the number of identifiers for
-which something happened.
-</p>
-
-<p>
- When <tt>ftrigr_updateb</tt> returns,
-<tt>genalloc_s(uint16_t, &amp;a-&gt;list)</tt> points to an array of
-<tt>genalloc_len(uint16_t, &amp;a-&gt;list)</tt> 16-bit unsigned
-integers. Those integers are ids waiting to be passed to
-<tt>ftrigr_check</tt> or <tt>ftrigr_checksa</tt>.
-The number of ids already acknowledged is stored in
-<tt>a-&gt;head</tt>, so the first unacknowledged id is
-<tt>genalloc_s(uint16_t, &amp;a-&gt;list)[a-&gt;head]</tt>.
+<a href="s6-ftrigrd.html">s6-ftrigrd</a> daemon. It returns -1 (and sets
+errno) if an error occurs, 0 if there were no events, and 1 if events
+were received.
 </p>
 
 <pre>
-int ftrigr_check (ftrigr_t *a, uint16_t id, char *what)
+int ftrigr_peek (ftrigr *a, uint32_t id, ftrigr_string *fs)
 </pre>
 
 <p>
@@ -263,49 +259,39 @@ call to <tt>ftrigr_updateb()</tt>.
 number may have been transmitted from
 <a href="s6-ftrigrd.html">s6-ftrigrd</a>. </li>
  <li> If no notification happened yet, returns 0. </li>
- <li> If something happened, writes the character that triggered the
-latest notification into <em>what</em> and returns the number of
-times that an event happened to this identifier since the last
-call to <tt>ftrigr_check()</tt>. </li>
+ <li> If something happened, returns 1, and <tt>fs</tt> contains
+the string of events that were received since the subscription or
+since the last call to <tt>ftrigr_ack</tt> (see below).
+<tt>fs-&gt;s</tt> is a pointer to the non-null-terminated string,
+and <tt>fs-&gt;len</tt> is its length. </li>
 </ul>
 
 <pre>
-int ftrigr_checksa (ftrigr_t *a, uint16_t id, stralloc *what)
+void ftrigr_ack (ftrigr *a, uint32_t id)
 </pre>
 
 <p>
- Checks whether an event happened to <em>id</em>. Use after a
-call to <tt>ftrigr_update()</tt>, as an alternative to <tt>ftrigr_check()</tt>.
+ Resets the stored string of events. The next invocation of
+<tt>ftrigr_peek()</tt> will only show new events, if any.
 </p>
 
-<ul>
- <li> If an error occurred, returns -1 and sets errno. The error
-number may have been transmitted from
-<a href="s6-ftrigrd.html">s6-ftrigrd</a>. </li>
- <li> If no notification happened yet, returns 0. </li>
- <li> If something happened, appends one character to the end of the <em>what</em>
-<a href="//skarnet.org/software/skalibs/libstddjb/stralloc.html">stralloc</a>
-for every time a notification was triggered since the last call
-to <tt>ftrigr_check()</tt>. Each character is the one that triggered
-a notification. The function then returns 1. </li>
-</ul>
-
 <pre>
-void ftrigr_ack (ftrigr_t *a, size_t n)
+int ftrigr_release (ftrigr *a, uint32_t id)
 </pre>
 
 <p>
- Acknowledges reading <em>n</em> ids from the id list updated by
-<tt>ftrigr_updateb</tt>.
+ Frees the resources used by subscription <tt>id</tt>. 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.
 </p>
 
-<pre>
-int ftrigr_update (ftrigr_t *a)
-</pre>
-
 <p>
- Acknowledges all the pending ids (i.e. clears the stored id list)
-then calls <tt>ftrigr_updateb()</tt>.
+ If subscription <tt>id</tt> was given the FTRIGR_REPEAT flag,
+use <tt>ftrigr_unsubscribe()</tt> instead. If you're not going
+to perform other subscriptions, <tt>ftrigr_end()</tt> will
+free all the resources without you needing to call
+<tt>ftrigr_release()</tt> first.
 </p>
 
 </body>
diff --git a/doc/libs6/s6-ftrigrd.html b/doc/libs6/s6-ftrigrd.html
index 7325c72..672b660 100644
--- a/doc/libs6/s6-ftrigrd.html
+++ b/doc/libs6/s6-ftrigrd.html
@@ -17,7 +17,7 @@
 <a href="//skarnet.org/">skarnet.org</a>
 </p>
 
-<h1> The s6-ftrigrd program </h1>
+<h1> The s6-ftrigrd internal program </h1>
 
 <p>
 s6-ftrigrd is a helper program that manages a set of subscriptions to fifodirs as well
@@ -29,24 +29,17 @@ events happen.
 <h2> Interface </h2>
 
 <p>
- s6-ftrigrd is not meant to be called directly.
-</p>
-
-<ul>
- <li> If the client program uses <tt>ftrigr_startf()</tt>, it spawns an instance of
+ s6-ftrigrd is not meant to be called directly. When the client calls
+<tt>ftrigr_start()</tt> or <tt>ftrigr_startf</tt>, 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. </li>
- <li> If the client program uses <tt>ftrigr_start()</tt>, then it tries to connect
-to a Unix domain socket. An ftrigrd <a href="../localservice.html">local service</a> should be listening to that
-socket, i.e. a Unix domain super-server such as
-<a href="s6-ipcserver.html">s6-ipcserver</a>
-spawning an s6-ftrigrd program on every connection. Then an s6-ftrigrd instance is created
-for the client. </li>
- <li> When the client uses <tt>ftrigr_end()</tt>, or closes s6-ftrigrd's stdin in
-any way, s6-ftrigrd exits 0. </li>
-</ul>
+notifications.
+</p>
+
+<p> When the client uses <tt>ftrigr_end()</tt>, or closes s6-ftrigrd's stdin in
+any way, s6-ftrigrd exits 0.
+</p>
 
 <p>
  s6-ftrigrd handles the grunt work of creating fifos in a
@@ -60,7 +53,7 @@ the client.
 
 <p>
  The connection management between the client and s6-ftrigrd is entirely done
-by the <em>textclient</em> library from skalibs.
+by the <em>sassclient</em> library from skalibs.
 </p>
 
 <p>
@@ -71,9 +64,13 @@ to read them. To avoid uncontrolled growth, make sure your client calls
 </p>
 
 <p>
- An s6-ftrigrd instance can only handle up to FTRIGRD_MAX (defined in <tt>s6/ftrigr.h</tt>)
-subscriptions at once. By default, this number is 1000, which is more than enough for
-any reasonable system.
+ The number of concurrent subscriptions that an s6-ftrigrd instance can handle is
+only limited by RAM and open file descriptors. It is likely that the latter is the
+bottleneck: s6-ftrigrd uses two file descriptors per fifodir. With a default
+limit of 1024 open file descriptors per process, it means that s6-ftrigrd can
+handle around 500 concurrent fifodirs, which is reasonable for most systems, but
+make sure to increase the open files resource limit before starting an ftrigr
+session if you need more.
 </p>
 
 </body>
-- 
cgit v1.3.1