From 543c1405653c48d23e19d03d7c62e9534fc9a110 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Thu, 23 Mar 2017 14:34:16 +0000
Subject:  Don't wait on locks by default (fail instead); add a -b option to
 get the waiting behaviour

 Also fix a few types in s6-rc-compile (unsigned int -> uint32_t for avltree indices)
---
 doc/s6-rc-bundle.html          | 11 ++++++++---
 doc/s6-rc-compile.html         |  7 ++++++-
 doc/s6-rc-db.html              | 27 ++++++++++++++++-----------
 doc/s6-rc-fdholder-filler.html |  7 +++++--
 doc/s6-rc-init.html            |  7 ++++++-
 doc/s6-rc-oneshot-run.html     |  7 ++++++-
 doc/s6-rc-update.html          |  7 ++++++-
 doc/s6-rc.html                 | 23 +++++++++++++++++------
 8 files changed, 70 insertions(+), 26 deletions(-)

(limited to 'doc')

diff --git a/doc/s6-rc-bundle.html b/doc/s6-rc-bundle.html
index 7647006..4bae71a 100644
--- a/doc/s6-rc-bundle.html
+++ b/doc/s6-rc-bundle.html
@@ -36,9 +36,9 @@ operation.
 
 <pre>
      s6-rc-bundle help
-     s6-rc-bundle [ -f ] [ -l <em>live</em> ] [ -c <em>compiled</em> ] add <em>bundlename</em> <em>contents...</em>
-     s6-rc-bundle [ -f ] [ -l <em>live</em> ] [ -c <em>compiled</em> ] delete <em>bundlenames...</em>
-     s6-rc-bundle [ -f ] [ -l <em>live</em> ] [ -c <em>compiled</em> ] multiple <em>args...</em>
+     s6-rc-bundle [ -f ] [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] add <em>bundlename</em> <em>contents...</em>
+     s6-rc-bundle [ -f ] [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] delete <em>bundlenames...</em>
+     s6-rc-bundle [ -f ] [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] multiple <em>args...</em>
 </pre>
 
 <ul>
@@ -66,6 +66,11 @@ when given a nonexisting name to delete (it will do nothing), or
 when given an existing name to add (it will replace the definition).
 By default, s6-rc-bundle will complain and exit when asked to delete a
 nonexistent name or to add an existing name. </li>
+ <li> <tt>-b</tt>&nbsp;: blocking lock. If the database is currently
+being used by another program, s6-rc-bundle will wait until that
+other program has released its lock on the database, then proceed.
+By default, s6-rc-bundle fails with an error message if the database
+is currently in use. </li>
 </ul>
 
 <h2> Exit codes </h2>
diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html
index 61f6dd2..cfacde1 100644
--- a/doc/s6-rc-compile.html
+++ b/doc/s6-rc-compile.html
@@ -36,7 +36,7 @@ the current service database via
 <h2> Interface </h2>
 
 <pre>
-     s6-rc-compile [ -v <em>verbosity</em> ] [ -u <em>uids</em> ] [ -g <em>gids</em> ] [ -h <em>fdhuser</em> ] <em>compiled</em> <em>source...</em>
+     s6-rc-compile [ -v <em>verbosity</em> ] [ -u <em>uids</em> ] [ -g <em>gids</em> ] [ -h <em>fdhuser</em> ]  [ -b ] <em>compiled</em> <em>source...</em>
 </pre>
 
 <ul>
@@ -77,6 +77,11 @@ numerical GIDs. </li>
 program, which maintains the pipes for the longrun pipelines, to run
 as user <em>fdhuser</em>. By default, it runs as the user owning
 the supervision tree, i.e. most likely <tt>root</tt>. </li>
+ <li> <tt>-b</tt>&nbsp;: make
+<a href="s6-rc-oneshot-runner.html">s6-rc-oneshot-runner</a>
+invocations wait instead of fail on lock contention. This
+should not change anything in practice, and you can ignore
+that option. </li>
 </ul>
 
 <p>
diff --git a/doc/s6-rc-db.html b/doc/s6-rc-db.html
index a9d8b9d..5c664f5 100644
--- a/doc/s6-rc-db.html
+++ b/doc/s6-rc-db.html
@@ -37,17 +37,17 @@ operation.
 
 <pre>
      s6-rc-db help
-     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] check
-     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] list all|services|oneshots|longruns|bundles
-     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] type <em>servicename</em>
-     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -u | -d ] timeout <em>atomicname</em>
-     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] contents <em>bundlename</em>
-     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -u | -d ] dependencies <em>servicename</em>
-     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] pipeline <em>longrunname</em>
-     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -u | -d ] script <em>oneshotname</em>
-     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] flags <em>atomicname</em>
-     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] atomics <em>servicename...</em>
-     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -u | -d ] all-dependencies <em>servicename...</em>
+     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] check
+     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] list all|services|oneshots|longruns|bundles
+     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] type <em>servicename</em>
+     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] [ -u | -d ] timeout <em>atomicname</em>
+     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] contents <em>bundlename</em>
+     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] [ -u | -d ] dependencies <em>servicename</em>
+     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] pipeline <em>longrunname</em>
+     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] [ -u | -d ] script <em>oneshotname</em>
+     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] flags <em>atomicname</em>
+     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] atomics <em>servicename...</em>
+     s6-rc-db [ -l <em>live</em> ] [ -c <em>compiled</em> ] [ -b ] [ -u | -d ] all-dependencies <em>servicename...</em>
 </pre>
 
 <ul>
@@ -78,6 +78,11 @@ ignored when it is irrelevant. </li>
  <li> <tt>-d</tt>&nbsp;: for commands that use different data
 depending on whether it's about bringing the service up or down,
 select the "down" data. This option is ignored when it is irrelevant. </li>
+ <li> <tt>-b</tt>&nbsp;: blocking lock. If the database is currently
+being used by another program, s6-rc-db will wait until that
+other program has released its lock on the database, then proceed.
+By default, s6-rc-db fails with an error message if the database
+is currently in use. </li>
 </ul>
 
 <h2> Exit codes </h2>
diff --git a/doc/s6-rc-fdholder-filler.html b/doc/s6-rc-fdholder-filler.html
index 83132fd..a835663 100644
--- a/doc/s6-rc-fdholder-filler.html
+++ b/doc/s6-rc-fdholder-filler.html
@@ -34,7 +34,7 @@ in internal scripts created by
 <h2> Interface </h2>
 
 <pre>
-     s6-rc-fdholder-filler [ -1 ] [ -t <em>timeout</em> ] <em>longrunnames...</em>
+     s6-rc-fdholder-filler [ -1 ] [ -t <em>timeout</em> ] &lt; <em>longrunnamesfile</em>
 </pre>
 
 <ul>
@@ -42,7 +42,10 @@ in internal scripts created by
 connected to the
 <a href="http://skarnet.org/software/s6/s6-fdholderd.html">s6-fdholderd</a>
 daemon instance managed by s6-rc as the internal <em>s6rc-fdholder</em> service. </li>
- <li> For every argument <em>longrun</em> in <em>longrunnames...</em>, it
+ <li> It reads a list of longrun names from its stdin, one per line.
+Empty lines are ignored; comments starting with <tt>#</tt> are ignored;
+leading whitespace is ignored, but trailing whitespace is not. </li>
+ <li> For every name <em>longrun</em> that it finds, it
 creates an anonymous pipe, and stores both ends of that pipe into the
 <a href="http://skarnet.org/software/s6/s6-fdholderd.html">s6-fdholderd</a>
 instance, with the <tt>pipe:s6-rc-r-<em>longrun</em></tt> (for the reading
diff --git a/doc/s6-rc-init.html b/doc/s6-rc-init.html
index 67ed7de..f24c20a 100644
--- a/doc/s6-rc-init.html
+++ b/doc/s6-rc-init.html
@@ -28,7 +28,7 @@ invocation of the
 <h2> Interface </h2>
 
 <pre>
-     s6-rc-init [ -c <em>compiled</em> ] [ -l <em>live</em> ] [ -t <em>timeout</em> ] <em>scandir</em>
+     s6-rc-init [ -c <em>compiled</em> ] [ -l <em>live</em> ] [ -t <em>timeout</em> ] [ -b ] <em>scandir</em>
 </pre>
 
 <ul>
@@ -74,6 +74,11 @@ filesystem. Default is
 <tt>/run/s6-rc</tt>. The default can be changed at compile time by
 giving the <tt>--livedir=<em>live</em></tt> option to
 <tt>./configure</tt>. </li>
+ <li> <tt>-b</tt>&nbsp;: blocking lock. If the database is currently
+being used by another program, s6-rc-init will wait until that
+other program has released its lock on the database, then proceed.
+By default, s6-rc-init fails with an error message if the database
+is currently in use. </li>
 </ul>
 
 <h2> Typical usage </h2>
diff --git a/doc/s6-rc-oneshot-run.html b/doc/s6-rc-oneshot-run.html
index 351e9e1..8cddcb5 100644
--- a/doc/s6-rc-oneshot-run.html
+++ b/doc/s6-rc-oneshot-run.html
@@ -33,7 +33,7 @@ in internal scripts created by
 <h2> Interface </h2>
 
 <pre>
-     s6-rc-oneshot-run [ -l <em>live</em> ] up|down <em>n</em>
+     s6-rc-oneshot-run [ -l <em>live</em> ] [ -b ] up|down <em>n</em>
 </pre>
 
 <ul>
@@ -49,6 +49,11 @@ live directory). </li>
  <li> <tt>-l&nbsp;<em>live</em></tt>&nbsp;: use the live directory in
 <em>live</em>. Default is <tt>/run/s6-rc</tt>, or what was given to the
 <tt>--livedir</tt> configure option at compile time. </li>
+ <li> <tt>-b</tt>&nbsp;: blocking lock. If the service database is currently
+being used by another program, s6-rc-oneshot-run will wait until that
+other program has released its lock on the database, then proceed.
+By default, s6-rc-oneshot-run fails with an error message if the database
+is currently in use. </li>
 </ul>
 
 <h2> Exit codes </h2>
diff --git a/doc/s6-rc-update.html b/doc/s6-rc-update.html
index e424f98..52ab42d 100644
--- a/doc/s6-rc-update.html
+++ b/doc/s6-rc-update.html
@@ -38,7 +38,7 @@ situations it cannot solve.
 <h2> Interface </h2>
 
 <pre>
-     s6-rc-update [ -n ] [ -v <em>verbosity</em> ] [ -t <em>timeout</em> ] [ -l <em>live</em> ] [ -f <em>convfile</em> ] <em>newdb</em>
+     s6-rc-update [ -n ] [ -v <em>verbosity</em> ] [ -t <em>timeout</em> ] [ -l <em>live</em> ] [ -f <em>convfile</em> ] [ -b ] <em>newdb</em>
 </pre>
 
 <ul>
@@ -95,6 +95,11 @@ The default can be changed at compile-time by giving the
  <li> <tt>-f&nbsp;<em>convfile</em></tt>&nbsp;: use the conversion
 file located at <em>convfile</em>. Default is <tt>/dev/null</tt>,
 meaning no special instructions. </li>
+ <li> <tt>-b</tt>&nbsp;: blocking lock. If the database is currently
+being used by another program, s6-rc-update will wait until that
+other program has released its lock on the database, then proceed.
+By default, s6-rc-update fails with an error message if the database
+is currently in use. </li>
 </ul>
 
 <h2> Transition details </h2>
diff --git a/doc/s6-rc.html b/doc/s6-rc.html
index 5e851d3..a6e64d9 100644
--- a/doc/s6-rc.html
+++ b/doc/s6-rc.html
@@ -44,9 +44,9 @@ especially when asking for a state change.
 
 <pre>
      s6-rc help
-     s6-rc [ -l live ] [ -a ] [ -u | -d ] list <em>servicenames...</em>
-     s6-rc [ -l live ] [ -a ] [ -u | -d ] listall <em>servicenames...</em>
-     s6-rc [ -l live ] [ -a ] [ -u | -d ] [ -p ] [ -v <em>verbosity</em> ] [ -n <em>dryrunthrottle</em> ] [ -t timeout ] change [ <em>servicenames...</em> ]
+     s6-rc [ -l live ] [ -b ] [ -a ] [ -u | -d ] list <em>servicenames...</em>
+     s6-rc [ -l live ] [ -b ] [ -a ] [ -u | -d ] listall <em>servicenames...</em>
+     s6-rc [ -l live ] [ -b ] [ -a ] [ -u | -d ] [ -p ] [ -v <em>verbosity</em> ] [ -n <em>dryrunthrottle</em> ] [ -t timeout ] change [ <em>servicenames...</em> ]
 </pre>
 
 <ul>
@@ -95,6 +95,14 @@ giving the <tt>--livedir=<em>live</em></tt> option to <tt>./configure</tt>. </li
 the selection. This is useful for instance at
 shutdown time: <tt>s6-rc -da change</tt>
 will stop all services. </li>
+ <li> <tt>-b</tt>&nbsp;: blocking lock. If the service database is currently
+being used by another program, s6-rc will wait until that
+other program has released its lock on the database, then proceed.
+By default, s6-rc fails with an error message if the service database
+is currently in use. The default is the safe behaviour: for instance,
+it will correctly detect and fail nested s6-rc invocations (which are
+an admin error), whereas <tt>s6-rc -b</tt> would deadlock in
+such a case. </li>
 </ul>
 
 <h3> Up or down </h3>
@@ -310,10 +318,13 @@ milliseconds to complete successfully.
 bringing up all its dependencies first (recursively).
 </p>
 
-<pre> s6-rc -ad change </pre>
+<pre> s6-rc -bad change </pre>
 <p>
- Brings down all the currently running services in an orderly manner.
-This is typically run at shutdown time.
+ Waits for any pending program of the s6-rc family to stop using
+the live database and current compiled service database, then
+brings down all the currently running services in an orderly manner.
+This is typically run at shutdown time. (And it's not necessarily
+a bad change!)
 </p>
 
 <pre> s6-rc -l /zork -ua listall <em>myservicebundle</em> </pre>
-- 
cgit v1.3.1