- Readiness notification support in s6-supervise

 - s6-notifywhenup deprecated
 - Change abundantly documented
 - rc for 2.1.4.0

9 files changed, 112 insertions, 23 deletions

diff --git a/doc/index.html b/doc/index.html
index 9f49abb..29e8181 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -84,11 +84,11 @@ with s6</a> </li>
  <li> GNU make, version 4.0 or later. Please be aware that s6 will not build
 with an earlier version. </li>
  <li> <a href="http://skarnet.org/software/skalibs/">skalibs</a> version
-2.3.2.0 or later. It's a build-time requirement. It's also a run-time
+2.3.5.1 or later. It's a build-time requirement. It's also a run-time
 requirement if you link against the shared version of the skalibs
 library. </li>
  <li> <a href="http://skarnet.org/software/execline/">execline</a> version
-2.1.1.0 or later. It's a build-time and run-time requirement. </li>
+2.1.2.2 or later. It's a build-time and run-time requirement. </li>
 </ul>
 
 <h3> Licensing </h3>
@@ -101,7 +101,7 @@ library. </li>
 <h3> Download </h3>
 
 <ul>
- <li> The current released version of s6 is <a href="s6-2.1.3.0.tar.gz">2.1.3.0</a>. </li>
+ <li> The current released version of s6 is <a href="s6-2.1.4.0.tar.gz">2.1.4.0</a>. </li>
  <li> Alternatively, you can checkout a copy of the s6 git repository:
 <pre> git clone git://git.skarnet.org/s6 </pre> </li>
  <li> There's also a
@@ -153,7 +153,8 @@ a user interface to control those processes and monitor service states.
 <li><a href="s6-svwait.html">The <tt>s6-svwait</tt> program</a></li>
 <li><a href="s6-svlisten1.html">The <tt>s6-svlisten1</tt> program</a></li>
 <li><a href="s6-svlisten.html">The <tt>s6-svlisten</tt> program</a></li>
-<li><a href="s6-notifywhenup.html">The <tt>s6-notifywhenup</tt> program</a> </li>
+<li><a href="s6-notifywhenup.html">The <tt>s6-notifywhenup</tt> program</a>
+<strong>(deprecated)</strong></li>
 </ul>
 
 <h4> Daemontools-like utilities </h4>
diff --git a/doc/notifywhenup.html b/doc/notifywhenup.html
index 6f9b06b..9a288ac 100644
--- a/doc/notifywhenup.html
+++ b/doc/notifywhenup.html
@@ -60,19 +60,16 @@ against the s6 library or use any s6-specific construct:
  daemons can simply write a line to a file descriptor of their choice,
 then close that file descriptor, when they're ready to serve. This is
 a generic mechanism that some daemons already implement.
-The administrator can
-then run the daemon under <a href="s6-notifywhenup.html">s6-notifywhenup</a>,
-which will properly catch the daemon's message and update a state file
-itself, then notify all the subscribers
-with a 'U' event, meaning that the service is now up. <br />
- Note that there is <em>still</em> a small race condition remaining:
-if the daemon writes a line then instantly dies, and the supervisor
-picks up the death before the <a href="s6-notifywhenup.html">s6-notifywhenup</a>
-program picks up the line, it is possible for the event sequence written
-to the fifodir to be wrong - 'd' before 'U'. This should be extremely
-rare, but unfortunately the race condition is unavoidable. The only
-way to be absolutely race-free is to have the daemon perform its
-readiness notification itself, which requires specific support.
+</p>
+
+<p>
+ s6 supports that mechanism natively: when the
+<a href="servicedir.html">service directory</a> for the daemon contains
+a valid <tt>notification-fd</tt> file, the daemon's supervisor, i.e. the
+<a href="s6-supervise.html">s6-supervise</a> program, will properly catch
+the daemon's message, update a state file (<tt>supervise/ready</tt>), then
+then notify all the subscribers
+with a 'U' event, meaning that the service is now up and ready.
 </p>
 
 <p>
diff --git a/doc/s6-notifywhenup.html b/doc/s6-notifywhenup.html
index cdd487c..cdfa693 100644
--- a/doc/s6-notifywhenup.html
+++ b/doc/s6-notifywhenup.html
@@ -18,6 +18,27 @@
 
 <h1> The s6-notifywhenup program </h1>
 
+<em>
+<p>
+Starting with s6-2.1.4.0, the s6-notifywhenup program has been deprecated,
+because there was still a case (albeit extremely rare) where a race
+condition would occur and readiness would be improperly advertised.
+Readiness notification for a service can now be achieved via a
+<tt>notification-fd</tt> file in the
+<a href="servicedir.html">service directory</a>, containing the
+number of the descriptor the service will write its readiness
+notification newline to. The notification will directly be picked by
+<a href="s6-supervise.html">s6-supervise</a>. <br />
+</p>
+
+<p>
+ Quick upgrade recipe: for every service using s6-notifywhenup,
+replace the s6-notifywhenup invocation in your run script with
+<tt>fdmove 1 3</tt>, then perform <tt>echo 3 &gt; notification-fd</tt>.
+Done!
+</p>
+</em>
+
 <p>
 s6-notifywhenup launches a daemon while listening to a file descriptor,
 and sends a 'U' event to a <a href="fifodir.html">fifodir</a> when it
diff --git a/doc/s6-supervise.html b/doc/s6-supervise.html
index 0c40aa1..78db1fa 100644
--- a/doc/s6-supervise.html
+++ b/doc/s6-supervise.html
@@ -59,6 +59,47 @@ if <tt>./run</tt> exits too quickly. </li>
 sends a <tt>'x'</tt> event to <tt>./event</tt> before exiting 0. </li>
 </ul>
 
+<h2> Options </h2>
+
+<p>
+ s6-supervise does not support options, because it is normally not run
+manually via a command line; it is usually launched by its own
+supervisor, <a href="s6-svscan.html">s6-svscan</a>.
+ However, the behaviour of an instance of s6-supervise can be tuned via
+various configuration files in the service directory. These files, and
+what they do, are listed on the
+<a href="servicedir.html">service directory documentation page</a>.
+</p>
+
+<h2> Readiness notification support </h2>
+
+<p>
+ If the <a href="servicedir.html">service directory</a> contains a valid
+<tt>notification-fd</tt> file when the service is started, or restarted,
+s6-supervise creates and listens to an additional pipe from the service
+for <a href="notifywhenup.html">readiness notification</a>. When the
+notification occurs, s6-supervise creates a <tt>./supervise/ready</tt>
+file containing the absolute time when readiness occurred, then sends
+a <tt>'U'</tt> event to <tt>./event</tt>. The <tt>./supervise/ready</tt>
+file is deleted on service death.
+</p>
+
+<p>
+ If the service is logged, i.e. if the service directory has a
+<tt>log</tt> subdirectory that is also a service directory, and the
+s6-supervise process has been launched by
+that is also <a href="s6-svscan.html">s6-svscan</a>, then by default
+the service's stdout goes into the logging pipe. If you set
+<tt>notification-fd</tt> to 1, the logging pipe will be overwritten
+by the notification pipe, which is probably not what you want. Instead,
+if your daemon writes a notification message to its stdout, you should
+set <tt>notification-fd</tt> to (for instance) 3, and redirect outputs
+in your run script. For instance, to redirect stderr to the logger and
+stdout to a <tt>notification-fd</tt> set to 3, you would start your
+daemon as <tt>fdmove -c 2 1 fdmove 1 3 prog...</tt> (in execline), or
+<tt>exec 2&gt;&amp;1 1&gt;&amp;3 3&lt;&amp;- prog...</tt> (in shell).
+</p>
+
 <h2> Signals </h2>
 
 <p>
diff --git a/doc/s6-svlisten.html b/doc/s6-svlisten.html
index c107b8e..2316a2b 100644
--- a/doc/s6-svlisten.html
+++ b/doc/s6-svlisten.html
@@ -64,8 +64,9 @@ support in the service programs. See <a href="notifywhenup.html">this page</a>
 for details. </li>
  <li> <tt>-U</tt>&nbsp;: really up. s6-svlisten will wait until the services are
 up <em>and</em> ready as reported by the services themselves. This requires
-specific support in the service programs, and the use of
-<a href="s6-notifywhenup.html">s6-notifywhenup</a> in the service's run script.
+specific support in the service programs, and the use of the
+<tt>notification-fd</tt> file in the
+<a href="servicedir.html">service directory</a>.
 See the explanation on <a href="notifywhenup.html">this page</a>. </li>
  <li> <tt>-d</tt>&nbsp;: down. s6-svlisten will wait until the services are down. </li>
  <li> <tt>-o</tt>&nbsp;: or. s6-svlisten will wait until <em>one</em> of the
diff --git a/doc/s6-svlisten1.html b/doc/s6-svlisten1.html
index 5a45fc8..a9e147a 100644
--- a/doc/s6-svlisten1.html
+++ b/doc/s6-svlisten1.html
@@ -52,8 +52,9 @@ support in the service programs. See <a href="notifywhenup.html">this page</a>
 for details. </li>
  <li> <tt>-U</tt>&nbsp;: really up. s6-svlisten1 will wait until the service is
 up <em>and</em> ready as reported by the daemon itself. This requires
-specific support in the daemon program, and the use of
-<a href="s6-notifywhenup.html">s6-notifywhenup</a> in the service's run script.
+specific support in the service programs, and the use of the
+<tt>notification-fd</tt> file in the
+<a href="servicedir.html">service directory</a>.
 See the explanation on <a href="notifywhenup.html">this page</a>. </li>
  <li> <tt>-d</tt>&nbsp;: down. s6-svlisten1 will wait until the service is down. </li>
  <li> <tt>-t&nbsp;<em>timeout</em></tt>&nbsp;: if the requested event has not
diff --git a/doc/s6-svwait.html b/doc/s6-svwait.html
index 90bc7eb..de209ea 100644
--- a/doc/s6-svwait.html
+++ b/doc/s6-svwait.html
@@ -48,8 +48,9 @@ support in the service programs. See <a href="notifywhenup.html">this page</a>
 for details. </li>
  <li> <tt>-U</tt>&nbsp;: really up. s6-svwait will wait until the services are
 up <em>and</em> ready as reported by the services themselves. This requires
-specific support in the service programs, and the use of
-<a href="s6-notifywhenup.html">s6-notifywhenup</a> in the service's run script.
+specific support in the service programs, and the use of the
+<tt>notification-fd</tt> file in the
+<a href="servicedir.html">service directory</a>.
 See the explanation on <a href="notifywhenup.html">this page</a>. </li>
  <li> <tt>-d</tt>&nbsp;: down. s6-svwait will wait until the services are down. </li>
  <li> <tt>-o</tt>&nbsp;: or. s6-svwait will wait until <em>one</em> of the
diff --git a/doc/servicedir.html b/doc/servicedir.html
index 501017b..7cebd53 100644
--- a/doc/servicedir.html
+++ b/doc/servicedir.html
@@ -103,6 +103,20 @@ automatically start it until it receives a <tt>s6-svc -u</tt> command. If no
 s6-supervise will not make the service a process group and session leader; the service
 will be run in the same process group as s6-supervise. If no <tt>nosetsid</tt> file
 exists, the service has its own process group and is started as a session leader. </li>
+ <li> An optional regular file named <tt>notification-fd</tt>. If such a file
+exists, it means that the service supports
+<a href="notifywhenup.html">readiness notification</a>. The file must only
+ contain an unsigned integer, which is the number of the file descriptor that
+the service writes its readiness notification to. (For instance, it should
+be 1 if the daemon is <a href="s6-ipcserverd">s6-ipcserverd</a> run with the
+<tt>-1</tt> option.) </li>
+  when a service is started, or restarted, by s6-supervise, if this file
+exists and contains a valid descriptor number, s6-supervise will wait for the
+notification from the service and broadcast readiness, i.e. any
+<a href="s6-svwait.html">s6-svwait -U</a>,
+<a href="s6-svlisten1.html">s6-svlisten1 -U</a> or
+<a href="s6-svlisten.html">s6-svlisten -U</a> processes will be
+triggered. </li>
  <li> A <a href="fifodir.html">fifodir</a> named <tt>event</tt>. It is automatically
 created by <a href="s6-supervise.html">s6-supervise</a> if it does not exist.
 <em>foo</em><tt>/event</tt>
diff --git a/doc/upgrade.html b/doc/upgrade.html
index 67e0ba1..a124800 100644
--- a/doc/upgrade.html
+++ b/doc/upgrade.html
@@ -18,6 +18,18 @@
 
 <h1> What has changed in s6 </h1>
 
+<h2> in 2.1.4.0 </h2>
+
+<ul>
+ <li> skalibs dependency bumped to 2.3.5.1. </li>
+ <li> execline dependency bumped to 2.1.2.2. </li>
+ <li> The <a href="s6-notifywhenup.html">s6-notifywhenup</a> command
+has been deprecated. Race-free
+<a href="notifywhenup.html">readiness notification</a> can now be implemented
+via the <tt>notification-fd</tt> file in a
+<a href="servicedir.html">service directory</a>. </li>
+</ul>
+
 <h2> in 2.1.3.0 </h2>
 
 <ul>