diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2023-09-11 08:13:01 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska@appnovation.com> | 2023-09-11 08:13:01 +0000 |
| commit | bc3863eaf3e4ae92eac8cd3ce0ca9dcb8915fc36 (patch) | |
| tree | 9c6d891677e1d48aa4219636bff1c103d9509a7d /doc | |
| parent | ddc088fba6016ae839afaa208b0a441869dc936f (diff) | |
| download | s6-bc3863eaf3e4ae92eac8cd3ce0ca9dcb8915fc36.tar.xz | |
Better s6-setlock; delete the s6lock subsystem
Signed-off-by: Laurent Bercot <ska@appnovation.com>
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/index.html | 10 | ||||
| -rw-r--r-- | doc/libs6/index.html | 2 | ||||
| -rw-r--r-- | doc/libs6/lock.html | 239 | ||||
| -rw-r--r-- | doc/libs6/s6lockd-helper.html | 56 | ||||
| -rw-r--r-- | doc/libs6/s6lockd.html | 75 | ||||
| -rw-r--r-- | doc/s6-setlock.html | 16 | ||||
| -rw-r--r-- | doc/upgrade.html | 6 |
7 files changed, 14 insertions, 390 deletions
diff --git a/doc/index.html b/doc/index.html index 4753a6b..9fdd34c 100644 --- a/doc/index.html +++ b/doc/index.html @@ -115,7 +115,7 @@ want nsswitch-like functionality: <h3> Download </h3> <ul> - <li> The current released version of s6 is <a href="s6-2.11.4.0.tar.gz">2.11.4.0</a>. </li> + <li> The current released version of s6 is <a href="s6-2.12.0.0.tar.gz">2.12.0.0</a>. </li> <li> Alternatively, you can checkout a copy of the <a href="//git.skarnet.org/cgi-bin/cgit.cgi/s6/">s6 git repository</a>: @@ -283,14 +283,6 @@ synchronization</a>. <li><a href="s6-instance-list.html">The <tt>s6-instance-list</tt> program</a></li> </ul> -<h4> Timed lock acquisition </h4> - -<ul> -<li><a href="s6-setlock.html">The <tt>s6-setlock</tt> program</a></li> -<li><a href="libs6/s6lockd.html">The <tt>s6lockd</tt> program</a></li> -<li><a href="libs6/s6lockd-helper.html">The <tt>s6lockd-helper</tt> internal program</a></li> -</ul> - <h4> fd-holding, a.k.a. the sensible part of socket activation </h4> <ul> diff --git a/doc/libs6/index.html b/doc/libs6/index.html index 1db2e5e..c934110 100644 --- a/doc/libs6/index.html +++ b/doc/libs6/index.html @@ -65,8 +65,6 @@ provides functions to check credentials against configuration files. </li> functions to subscribe to fifodirs and be notified of events. </li> <li> The <a href="ftrigw.html">s6/ftrigw.h</a> header provides functions to manage fifodirs and send notifications to them. </li> - <li> The <a href="lock.html">s6/lock.h</a> header provides -functions to acquire locks with a timeout. </li> <li> The <a href="fdholder.html">s6/fdholder.h</a> header provides functions to communicate with a <a href="../s6-fdholderd.html">s6-fdholderd</a> server and exchange diff --git a/doc/libs6/lock.html b/doc/libs6/lock.html deleted file mode 100644 index 1cc896d..0000000 --- a/doc/libs6/lock.html +++ /dev/null @@ -1,239 +0,0 @@ -<html> - <head> - <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <meta http-equiv="Content-Language" content="en" /> - <title>s6: the s6lock library interface</title> - <meta name="Description" content="s6: the s6lock library interface" /> - <meta name="Keywords" content="s6 timed lock s6lock libs6 library interface" /> - <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> - </head> -<body> - -<p> -<a href="index.html">libs6</a><br /> -<a href="../">s6</a><br /> -<a href="//skarnet.org/software/">Software</a><br /> -<a href="//skarnet.org/">skarnet.org</a> -</p> - -<h1> The <tt>s6lock</tt> library interface </h1> - -<h2> General information </h2> - -<p> - <tt>s6lock</tt> is a C interface to timed locks. Unix natively provides -locks, but the locking primitives are synchronous, so either they are -unbounded in execution time or they require polling. s6lock provides -poll-free locks that can timeout during attempted acquisition. -</p> - -<h2> Programming </h2> - -<ul> - <li> Check the <tt>s6/lock.h</tt> header -for the prototypes. The functions documented here are -often simplified macros, for instance relying on the STAMP global variable -to hold the current time. Fully reentrant functions with more control -options are usually available. </li> - <li> Given the nature of the s6lock library, it makes sense to use a -<a href="../localservice.html">s6lockd service</a> concurrently -accessed by several applications using such locks to gate shared -resources. </li> - <li> If you're not using an s6lockd service, -make sure your application is not disturbed by children it doesn't -know it has. Using nonblocking waits, ignoring pids you don't know, and -using a -<a href="//skarnet.org/software/skalibs/libstddjb/selfpipe.html">self-pipe</a> -if your application is built around an event loop, are good programming -practices. </li> -</ul> - -<h3> Starting and ending a session </h3> - -<pre> -s6lock_t a = S6LOCK_ZERO ; -tain_t deadline ; - -tain_now_g() ; -tain_addsec_g(&deadline, 2) - -char const *path = S6LOCK_IPCPATH ; -s6lock_start_g(&a, path, &deadline) ; -// char const *lockdir = "/tmp/lock" ; -// s6lock_startf_g(&a, lockdir, &deadline) ; -</pre> - -<p> -<tt>s6lock_start_g</tt> starts a session by connecting to an s6lockd service -listening on <em>path</em>. The working directory is set by the administrator -of the service. <br /> -<tt>s6lock_startf_g</tt> starts a session with an s6lockd process as a child, -using <em>lockdir</em> as its working directory. -<br /> -<tt>a</tt> is an s6lock_t structure that must be declared in the stack and -initialized to S6LOCK_ZERO. -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. - -Only local interprocess communications are involved; unless your system is -heavily overloaded, the function should return near-instantly. One or two -seconds of delay between the current time and <tt>deadline</tt> should be -enough: if the function takes more than that to return, then there is a -problem with the underlying processes. -</p> - -<p> - You can have more than one session open in parallel, by declaring -several distinct <tt>s6lock_t</tt> structures and calling -<tt>s6lock_startf_g</tt> (or <tt>s6lock_start_g</tt>) more than once. -However, one single session can handle -virtually as many concurrent locks as your application needs, so -opening several sessions is only useful if you need to acquire locks -in various distinct lock directories. -</p> - -<pre> -s6lock_end(&a) ; -</pre> - -<p> -<tt>s6lock_end</tt> frees all the resources used by the session. The -<tt>a</tt> structure is then reusable for another session. -</p> - -<h3> Acquiring and releasing locks </h3> - -<pre> -uint16_t id ; -char const *file = "lockfile" ; -tain_t limit ; -tain_t deadline ; - -int r = s6lock_acquire_sh_g (&a, &id, file, &limit, &deadline) ; -/* int r = s6lock_acquire_ex_g (&a, &id, file, &limit, &deadline) ; */ -r = s6lock_release_g(&a, id, &deadline) ; -</pre> - -<p> -<tt>s6lock_acquire_sh_g</tt> instructs the -<a href="s6lockd.html">s6lockd daemon</a>, related to the open -session represented by the <tt>a</tt> handle, to try and acquire a -shared lock on the -<em>file</em> file located under that daemon's working directory -(typically <tt>/var/lock</tt>). <em>file</em> will be interpreted as -relative to the daemon's working directory even if it starts with a -slash; however, slashes in the middle of <em>file</em> are likely to -result in an error. -</p> - -<p> -<em>limit</em> and <em>deadline</em> are two absolute dates. -<em>deadline</em> is a deadline for the execution of the -function: if by <em>deadline</em> the function has not returned, -then it instantly returns 0 and sets errno to ETIMEDOUT. The -function is normally near-instantaneous, so <em>deadline</em> can -be very close in the future and serves only as a protection against -malicious servers. <em>limit</em> is the acquisition deadline: if -by <em>limit</em> the daemon still has not been able to acquire a lock -on <em>file</em>, then it will report a timeout to the client. -</p> - -<p> -The function returns 1 in case of success, or 0 if an error occurs, -with errno set to a suitable value. If it succeeds, then a 16-bit -number is stored into *<em>id</em>; this number serves as an identifier -for this lock. -</p> - -<p> -<tt>s6lock_acquire_ex_g</tt> works just like <tt>s6lock_acquire_sh_g</tt>, -except that the daemon tries to acquire an exclusive lock. -</p> - -<p> -<tt>s6lock_release_g</tt> releases the lock identified by <em>id</em>. -It normally returns 1. It can return 0 with errno set to a suitable -value if it fails. <em>id</em> is not valid after the corresponding -lock has been released. The function normally returns instantly, with -<em>deadline</em> as a safeguard. -</p> - -<h3> Asynchronously waiting for locks </h3> - -<p> -<em> (from now on, the functions are listed with their prototypes instead -of usage examples.) </em> -</p> - -<pre> -int s6lock_fd (s6lock_t const *a) -</pre> - -<p> - Returns a file descriptor to select on for reading. Do not -<tt>read()</tt> it though. -</p> - -<pre> -int s6lock_update (s6lock_t *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="s6lockd.html">s6lockd</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>s6lock_update</tt> returns, -<tt>genalloc_s(uint16_t, &a->list)</tt> points to an array of -<tt>genalloc_len(uint16_t, &a->list)</tt> 16-bit unsigned -integers. Those integers are ids waiting to be passed to -<tt>s6lock_check</tt>. -</p> - -<pre> -int s6lock_check (s6lock_t *a, uint16_t id, char *what) -</pre> - -<p> - Checks whether the lock identified by <em>id</em> has -been acquired. Use after a call to <tt>s6lock_update()</tt>. -</p> - -<ul> - <li> If an error occurred, returns -1 and sets errno. The error -number may have been transmitted from -<a href="s6lockd.html">s6lockd</a>. </li> - <li> If the lock has not been acquired yet, returns 0. </li> - <li> If the lock has been acquired, returns 1. </li> -</ul> - -<h3> Synchronously waiting for locks </h3> - -<p> -<code> int s6lock_wait_or_g (s6lock_t *a, uint16_t const *idlist, unsigned int n, tain_t const *deadline) </code> <br /> -Synchronously waits for <em>one</em> of the locks represented by the array pointed to -by <em>idlist</em> of length <em>n</em> to be acquired. Returns -1 if it fails, -or a nonnegative number on success, which is the index in <em>idlist</em> of the -acquired lock's id. If no result has been obtained by <em>deadline</em>, the -function returns -1 ETIMEDOUT. -</p> - -<p> -<code> int s6lock_wait_and_g (s6lock_t *a, uint16_t const *idlist, unsigned int n, tain_t const *deadline) </code> <br /> -Synchronously waits for <em>all</em> of the locks represented by the array pointed to -by <em>idlist</em> of length <em>n</em> to be acquired. Returns -1 if it fails and -0 if it succeeds. If no result has been obtained by <em>deadline</em>, the -function returns -1 ETIMEDOUT. -</p> - -</body> -</html> diff --git a/doc/libs6/s6lockd-helper.html b/doc/libs6/s6lockd-helper.html deleted file mode 100644 index bc3d1a5..0000000 --- a/doc/libs6/s6lockd-helper.html +++ /dev/null @@ -1,56 +0,0 @@ -<html> - <head> - <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <meta http-equiv="Content-Language" content="en" /> - <title>s6: the s6lockd-helper internal program</title> - <meta name="Description" content="s6: the s6lockd-helper internal program" /> - <meta name="Keywords" content="s6 s6lockd-helper lockd asynchronous timed lock daemon helper" /> - <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> - </head> -<body> - -<p> -<a href="index.html">libs6</a><br /> -<a href="../">s6</a><br /> -<a href="//skarnet.org/software/">Software</a><br /> -<a href="//skarnet.org/">skarnet.org</a> -</p> - -<h1> The <tt>s6lockd-helper</tt> program </h1> - -<p> -<tt>s6lockd-helper</tt> is a helper program for the s6lock daemon. -It just acquires a lock and holds it until it is killed or told to -exit by its parent daemon. -</p> - -<h2> Interface </h2> - -<p> - s6lockd-helper is not meant to be invoked directly by the user: -it will be spawned by the -<a href="s6lockd.html">s6lockd</a> program. -</p> - -<h2> Notes </h2> - -<ul> - <li> s6lockd-helper blocks on lock acquisition until it succeeds. It then -notifies its parent. It exits when its parent tells him to (i.e. when the -client asks for lock release). During the lock acquisition phase, it can -be killed if its parent detects a timeout. </li> - <li> One s6lockd-helper process per lock is the only way (apart from -threads) to implement timed lock acquisition. This can lead to a lot of -s6lockd-helper processes, but this is not a problem: - <ul> - <li> Processes are not a scarce resource. Today's schedulers work in O(1), -or in O(a function of the number of runnable processes), which means that a -sleeping process takes no scheduling time at all </li> - <li> s6lockd-helper is extremely tiny. Every instance should use up at -most one or two pages of non-sharable memory. </li> - </ul> </li> -</ul> - -</body> -</html> diff --git a/doc/libs6/s6lockd.html b/doc/libs6/s6lockd.html deleted file mode 100644 index 089de57..0000000 --- a/doc/libs6/s6lockd.html +++ /dev/null @@ -1,75 +0,0 @@ -<html> - <head> - <meta name="viewport" content="width=device-width, initial-scale=1.0" /> - <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> - <meta http-equiv="Content-Language" content="en" /> - <title>s6: the s6lockd internal program</title> - <meta name="Description" content="s6: the s6lockd internal program" /> - <meta name="Keywords" content="s6 s6lockd lockd asynchronous timed lock daemon" /> - <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> - </head> -<body> - -<p> -<a href="index.html">libs6</a><br /> -<a href="../">s6</a><br /> -<a href="//skarnet.org/software/">Software</a><br /> -<a href="//skarnet.org/">skarnet.org</a> -</p> - -<h1> The <tt>s6lockd</tt> program </h1> - -<p> -<tt>s6lockd</tt> is the s6lock daemon. It is a program that manages -a set of lock files in a given directory, and associated timeouts. -</p> - -<h2> Interface </h2> - -<p> - s6lockd does not fork, does not background itself automatically, -and does not use syslog. It is not meant to be run directly by the -user: it will be spawned by the -<a href="s6lock.html">s6lock client library</a>. -</p> - -<p> - There are 2 ways to use s6lockd: -</p> - -<ol> - <li> Use the <tt>s6lock_startf()</tt> library call. -An <tt>s6lockd</tt> child will then be spawned from your -calling process, and automatically reaped when you call -<tt>s6lock_end()</tt>. It requires care with applications that -trap SIGCHLD. It also requires care with lock file permissions: -an s6lockd instance might not be able -to open a lock file created by a former instance run by another -client with different permissions. </li> - <li> Use the <tt>s6lock_start()</tt> library call, together with a -<a href="../localservice.html">s6lockd service</a>. -For once, <em>this is the recommended setup</em>: s6lockd creates empty -lock files, and having all s6lockd instances run under the same user -simplifies permissions management considerably. </li> -</ol> - -<p> -When run as a service, s6lockd has no "standalone" mode: it is -designed to work with a Unix -domain super-server, like -<a href="../s6-ipcserver.html">s6-ipcserver</a>. -s6lockd follows the <a href="https://cr.yp.to/proto/ucspi.txt">UCSPI</a> -interface, it can be directly executed from the super-server. -</p> - -<h2> Notes </h2> - -<ul> - <li> Unix does not natively provide a way to stop blocking on a lock -acquisition after a timeout. To emulate such behaviour, s6lockd actually -spawns an <a href="s6lockd-helper.html">s6lockd-helper</a> child per -requested lock. </li> -</ul> - -</body> -</html> diff --git a/doc/s6-setlock.html b/doc/s6-setlock.html index c2e8fbf..91e2fcc 100644 --- a/doc/s6-setlock.html +++ b/doc/s6-setlock.html @@ -25,7 +25,7 @@ s6-setlock takes a lock on a file, then executes into another program. <h2> Interface </h2> <pre> - s6-setlock [ -n | -N | -t <em>timeout</em> ] [ -r | -w ] <em>file</em> <em>prog...</em> + s6-setlock [ -n | -N ] [ -t <em>timeout</em> ] [ -d <em>fd</em> ] [ -r | -w ] <em>file</em> <em>prog...</em> </pre> <ul> @@ -46,20 +46,20 @@ the lock after <em>timeout</em> milliseconds, it will exit 1. </li> <li> <tt>-r</tt> : shared lock. Other shared locks on the same file will not prevent the lock from being acquired (but an exclusive lock will). </li> <li> <tt>-w</tt> : exclusive lock. This is the default. </li> + <li> <tt>-d <em>fd</em></tt> : make the lock visible in <em>prog</em> +on file descriptor <em>fd</em>. </li> </ul> <h2> Notes </h2> <ul> - <li> s6-setlock leaks an open file descriptor into the <em>prog</em> + <li> +s6-setlock leaks an open file descriptor into the <em>prog</em> execution. This is intended: the fd holds the lock, which is released when <em>prog</em> exits. <em>prog</em> must not touch fds it does not -know about. </li> - <li> If the timed lock option is chosen, s6-setlock does not acquire the lock -itself. Instead, it spawns a <a href="libs6/s6lockd-helper.html">s6lockd-helper</a> -process that acquires the lock while s6-setlock controls the timeout; the -s6lockd-helper process then holds the lock and lives as long as -<em>prog</em>. </li> +know about; by default it has no need to know the descriptor that holds +the lock. But if you need to officialize the presence of the lock in +<em>prog</em>, that's where the <tt>-d</tt> option comes in. </li> </ul> </body> diff --git a/doc/upgrade.html b/doc/upgrade.html index 2c184a6..f440d90 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -18,7 +18,7 @@ <h1> What has changed in s6 </h1> -<h2> in 2.11.4.0 </h2> +<h2> in 2.12.0.0 </h2> <ul> <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> @@ -31,6 +31,10 @@ recommended dependency bumped to 2.9.4.0. </li> <li> New <tt>-t</tt> option to <a href="s6-log.html">s6-log</a>. </li> <li> <a href="s6-svscan.html">s6-svscan</a> rewrite; new options <tt>-C</tt> and <tt>-L</tt>. </li> + <li> Obsolete <tt>s6lockd</tt> subsystem removed. </li> + <li> <a href="s6-setlock.html">s6-setlock</a> now has a <tt>-d</tt> +option to pin the lock to a fixed descriptor. Timeout management also +simplified. </li> </ul> <h2> in 2.11.3.2 </h2> |