From d73a8330016fbf172f8e3521b879502b9139a970 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 14 Jan 2015 00:48:32 +0000 Subject: - Parallel build fix - Complete readiness notification via supervise/ready - Version updated to 2.0.1.0, release candidate --- doc/index.html | 6 +++--- doc/notifywhenup.html | 36 +++++++++++++++++++----------------- doc/s6-notifywhenup.html | 3 ++- doc/s6-svwait.html | 12 +++++++----- doc/upgrade.html | 8 ++++++++ 5 files changed, 39 insertions(+), 26 deletions(-) (limited to 'doc') diff --git a/doc/index.html b/doc/index.html index bf8d0ae..1507705 100644 --- a/doc/index.html +++ b/doc/index.html @@ -52,9 +52,9 @@ supervision that might help you understand the basics.
  • A POSIX-compliant system with a standard C development environment
  • GNU make, version 4.0 or later
  • skalibs version -2.1.0.0 or later
    • +2.2.0.0 or later
  • execline version -2.0.0.0 or later
    • +2.0.1.1 or later

    Licensing

    @@ -67,7 +67,7 @@ supervision that might help you understand the basics.

    Download

    diff --git a/doc/notifywhenup.html b/doc/notifywhenup.html index f73e2aa..6847cb2 100644 --- a/doc/notifywhenup.html +++ b/doc/notifywhenup.html @@ -42,25 +42,28 @@ daemon may not be ready yet.

    Reliable startup notifications need support from the daemons themselves. -Daemons should notify the outside world when the service they are providing -is reliably up - because only they know when it is the case. -

    - -

    - s6 provides two ways for daemons to perform startup notification. +Daemons should do two things to signal the outside world that they are +ready:

      -
    1. Daemons can use the ftrigw_notify() function, provided in -the ftrigw library. This is extremely -simple and efficient, but requires specific s6 support in the daemon.
      2. -
    2. Daemons can write a line to a file descriptor of their choice, +
    3. Update a state file, so other processes can get a snapshot +of the daemon's state
      4. +
    4. Send an event to processes waiting for a state change.
      5. +
    + +

    + This is complex to implement in every single daemon, so s6 provides +tools to make it easier for daemon authors, without any need to link +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, and does not -require anything specific in the daemon's code. The administrator can +a generic mechanism that some daemons already implement. +The administrator can then run the daemon under s6-notifywhenup, -which will properly catch the daemon's message and notify all the subscribers -with a 'U' event, meaning that the service is now up.

    +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.
    Note that there is still a small race condition remaining: if the daemon writes a line then instantly dies, and the supervisor picks up the death before the s6-notifywhenup @@ -69,11 +72,10 @@ 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. - - +

    - The second method should really be implemented in every long-running + This method should really be implemented in every long-running program providing a service. When it is not the case, it's impossible to provide reliable startup notifications, and subscribers should then be content with the unreliable 'u' events provided by s6-supervise. diff --git a/doc/s6-notifywhenup.html b/doc/s6-notifywhenup.html index f192ca4..b772925 100644 --- a/doc/s6-notifywhenup.html +++ b/doc/s6-notifywhenup.html @@ -38,7 +38,8 @@ needed.

  • s6-notifywhenup forks and executes prog... as the parent, with a pipe from prog...'s stdout to the child.
  • The child waits for a newline (\n) to be written -on the pipe. When it gets it, it sends a 'U' event to the +on the pipe. When it gets it, it creates an empty +./supervise/ready file then sends a 'U' event to the ./event fifodir.
  • The child exits 0.
    • diff --git a/doc/s6-svwait.html b/doc/s6-svwait.html index 6e15704..5f3cb08 100644 --- a/doc/s6-svwait.html +++ b/doc/s6-svwait.html @@ -33,7 +33,7 @@ s6-svwait only waits for notifications; it never polls.

    s6-svwait monitors one or more service -directories given as its arguments, waiting for a state (up or down) to +directories given as its arguments, waiting for a state (ready, up or down) to happen. It exits 0 when the wanted condition becomes true.

    @@ -46,8 +46,10 @@ This is the default; it is not reliable, but it does not depend on specific support in the service programs. See this page for details.
  • -U : really up. s6-svwait will wait until the services are -up, as reported by the services themselves. This requires specific support in the -service programs: see the explanation on this page.
    • +up and ready as reported by the services themselves. This requires +specific support in the service programs, and the use of +s6-notifywhenup in the service's run script. +See the explanation on this page.
  • -d : down. s6-svwait will wait until the services are down.
  • -o : or. s6-svwait will wait until one of the given services comes up or down.
    • @@ -59,13 +61,13 @@ to stderr and exit 1. By default, timeout is 0, which means no time limit. -

    Internals

    s6-svwait spawns a s6-ftrigrd child to listen to notifications sent by s6-supervise. -It also checks supervise/status files to get the current service +It also checks supervise/status files, as well as the +supervise/ready files if necessary, to get the current service states, so it is immune to race conditions.

    diff --git a/doc/upgrade.html b/doc/upgrade.html index 789d425..0851534 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -17,6 +17,14 @@

    What has changed in s6

    +

    in 2.0.1.0

    + + +

    in 2.0.0.1