s6: the s6lock library interface

From bc3863eaf3e4ae92eac8cd3ce0ca9dcb8915fc36 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Mon, 11 Sep 2023 08:13:01 +0000 Subject: Better s6-setlock; delete the s6lock subsystem Signed-off-by: Laurent Bercot --- doc/index.html | 10 +- doc/libs6/index.html | 2 - doc/libs6/lock.html | 239 ------------------------------------------ doc/libs6/s6lockd-helper.html | 56 ---------- doc/libs6/s6lockd.html | 75 ------------- doc/s6-setlock.html | 16 +-- doc/upgrade.html | 6 +- 7 files changed, 14 insertions(+), 390 deletions(-) delete mode 100644 doc/libs6/lock.html delete mode 100644 doc/libs6/s6lockd-helper.html delete mode 100644 doc/libs6/s6lockd.html (limited to 'doc') 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:

Download

The current released version of s6 is 2.11.4.0.
The current released version of s6 is 2.12.0.0.
Alternatively, you can checkout a copy of the s6 git repository: @@ -283,14 +283,6 @@ synchronization.
The s6-instance-list program

Timed lock acquisition

- -

fd-holding, a.k.a. the sensible part of socket activation

The s6/ftrigw.h header provides functions to manage fifodirs and send notifications to them.
The s6/lock.h header provides -functions to acquire locks with a timeout.
The s6/fdholder.h header provides functions to communicate with a s6-fdholderd 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 @@ - - - - - - s6: the s6lock library interface - - - - - - -
-libs6
-s6
-Software
-skarnet.org -
- -
The s6lock library interface
- -
General information
- -
- s6lock 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. -
- -
Programming
- -
- Check the s6/lock.h 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.
- Given the nature of the s6lock library, it makes sense to use a -s6lockd service concurrently -accessed by several applications using such locks to gate shared -resources.
- 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 -self-pipe -if your application is built around an event loop, are good programming -practices.
- -
Starting and ending a session
- -
```
-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) ;
-
```
- -
-s6lock_start_g starts a session by connecting to an s6lockd service -listening on path. The working directory is set by the administrator -of the service.
-s6lock_startf_g starts a session with an s6lockd process as a child, -using lockdir as its working directory. -
-a 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. -
-
-If the absolute time deadline 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 deadline should be -enough: if the function takes more than that to return, then there is a -problem with the underlying processes. -
- -
- You can have more than one session open in parallel, by declaring -several distinct s6lock_t structures and calling -s6lock_startf_g (or s6lock_start_g) 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. -
- -
```
-s6lock_end(&a) ;
-
```
- -
-s6lock_end frees all the resources used by the session. The -a structure is then reusable for another session. -
- -
Acquiring and releasing locks
- -
```
-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) ;
-
```
- -
-s6lock_acquire_sh_g instructs the -s6lockd daemon, related to the open -session represented by the a handle, to try and acquire a -shared lock on the -file file located under that daemon's working directory -(typically /var/lock). file will be interpreted as -relative to the daemon's working directory even if it starts with a -slash; however, slashes in the middle of file are likely to -result in an error. -
- -
-limit and deadline are two absolute dates. -deadline is a deadline for the execution of the -function: if by deadline the function has not returned, -then it instantly returns 0 and sets errno to ETIMEDOUT. The -function is normally near-instantaneous, so deadline can -be very close in the future and serves only as a protection against -malicious servers. limit is the acquisition deadline: if -by limit the daemon still has not been able to acquire a lock -on file, then it will report a timeout to the client. -
- -
-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 *id; this number serves as an identifier -for this lock. -
- -
-s6lock_acquire_ex_g works just like s6lock_acquire_sh_g, -except that the daemon tries to acquire an exclusive lock. -
- -
-s6lock_release_g releases the lock identified by id. -It normally returns 1. It can return 0 with errno set to a suitable -value if it fails. id is not valid after the corresponding -lock has been released. The function normally returns instantly, with -deadline as a safeguard. -
- -
Asynchronously waiting for locks
- -
- (from now on, the functions are listed with their prototypes instead -of usage examples.) -
- -
```
-int s6lock_fd (s6lock_t const *a)
-
```
- -
- Returns a file descriptor to select on for reading. Do not -read() it though. -
- -
```
-int s6lock_update (s6lock_t *a)
-
```
- -
- Call this function whenever the fd checks readability: it will -update a's internal structures with information from the -s6lockd daemon. It returns -1 if an error -occurs; in case of success, it returns the number of identifiers for -which something happened. -
- -
- When s6lock_update returns, -genalloc_s(uint16_t, &a->list) points to an array of -genalloc_len(uint16_t, &a->list) 16-bit unsigned -integers. Those integers are ids waiting to be passed to -s6lock_check. -
- -
```
-int s6lock_check (s6lock_t *a, uint16_t id, char *what)
-
```
- -
- Checks whether the lock identified by id has -been acquired. Use after a call to s6lock_update(). -
- -
- If an error occurred, returns -1 and sets errno. The error -number may have been transmitted from -s6lockd.
- If the lock has not been acquired yet, returns 0.
- If the lock has been acquired, returns 1.
- -
Synchronously waiting for locks
- -
- int s6lock_wait_or_g (s6lock_t *a, uint16_t const *idlist, unsigned int n, tain_t const *deadline)
-Synchronously waits for one of the locks represented by the array pointed to -by idlist of length n to be acquired. Returns -1 if it fails, -or a nonnegative number on success, which is the index in idlist of the -acquired lock's id. If no result has been obtained by deadline, the -function returns -1 ETIMEDOUT. -
- -
- int s6lock_wait_and_g (s6lock_t *a, uint16_t const *idlist, unsigned int n, tain_t const *deadline)
-Synchronously waits for all of the locks represented by the array pointed to -by idlist of length n to be acquired. Returns -1 if it fails and -0 if it succeeds. If no result has been obtained by deadline, the -function returns -1 ETIMEDOUT. -
- - - 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 @@ - - - - - - s6: the s6lockd-helper internal program - - - - - - -
-libs6
-s6
-Software
-skarnet.org -
- -
The s6lockd-helper program
- -
-s6lockd-helper 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. -
- -
Interface
- -
- s6lockd-helper is not meant to be invoked directly by the user: -it will be spawned by the -s6lockd program. -
- -
Notes
- -
- 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.
- 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: -
  - 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
  - s6lockd-helper is extremely tiny. Every instance should use up at -most one or two pages of non-sharable memory.
- - - 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 @@ - - - - - - s6: the s6lockd internal program - - - - - - -
-libs6
-s6
-Software
-skarnet.org -
- -
The s6lockd program
- -
-s6lockd is the s6lock daemon. It is a program that manages -a set of lock files in a given directory, and associated timeouts. -
- -
Interface
- -
- 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 -s6lock client library. -
- -
- There are 2 ways to use s6lockd: -
- -
1. Use the s6lock_startf() library call. -An s6lockd child will then be spawned from your -calling process, and automatically reaped when you call -s6lock_end(). 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.
2. Use the s6lock_start() library call, together with a -s6lockd service. -For once, this is the recommended setup: s6lockd creates empty -lock files, and having all s6lockd instances run under the same user -simplifies permissions management considerably.
- -
-When run as a service, s6lockd has no "standalone" mode: it is -designed to work with a Unix -domain super-server, like -s6-ipcserver. -s6lockd follows the UCSPI -interface, it can be directly executed from the super-server. -
- -
Notes
- -
- 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 s6lockd-helper child per -requested lock.
- - - 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.
Interface
```
-     s6-setlock [ -n | -N | -t timeout ] [ -r | -w ] file prog...
+     s6-setlock [ -n | -N ] [ -t timeout ] [ -d fd ] [ -r | -w ] file prog...
 
```
- -r : shared lock. Other shared locks on the same file will not prevent the lock from being acquired (but an exclusive lock will).
- -w : exclusive lock. This is the default.
- -d fd : make the lock visible in prog +on file descriptor fd.
Notes
- s6-setlock leaks an open file descriptor into the prog +
- +s6-setlock leaks an open file descriptor into the prog execution. This is intended: the fd holds the lock, which is released when prog exits. prog must not touch fds it does not -know about.
- If the timed lock option is chosen, s6-setlock does not acquire the lock -itself. Instead, it spawns a s6lockd-helper -process that acquires the lock while s6-setlock controls the timeout; the -s6lockd-helper process then holds the lock and lives as long as -prog.
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 @@
What has changed in s6
-
in 2.11.4.0
+
in 2.12.0.0
- skalibs @@ -31,6 +31,10 @@ recommended dependency bumped to 2.9.4.0.
- New -t option to s6-log.
- s6-svscan rewrite; new options -C and -L.
- Obsolete s6lockd subsystem removed.
- s6-setlock now has a -d +option to pin the lock to a fixed descriptor. Timeout management also +simplified.
in 2.11.3.2
-- cgit v1.2.3

Download

Timed lock acquisition

fd-holding, a.k.a. the sensible part of socket activation

The `s6lock` library interface

General information

Programming

Starting and ending a session

Acquiring and releasing locks

Asynchronously waiting for locks

Synchronously waiting for locks

The `s6lockd-helper` program

Interface

Notes

The `s6lockd` program

Interface

Notes

Interface

Notes

What has changed in s6

in 2.11.4.0

in 2.12.0.0

in 2.11.3.2

Download

Timed lock acquisition

fd-holding, a.k.a. the sensible part of socket activation

The s6lock library interface

General information

Programming

Starting and ending a session

Acquiring and releasing locks

Asynchronously waiting for locks

Synchronously waiting for locks

The s6lockd-helper program

Interface

Notes

The s6lockd program

Interface

Notes

Interface

Notes

What has changed in s6

in 2.11.4.0

in 2.12.0.0

in 2.11.3.2

The `s6lock` library interface

The `s6lockd-helper` program

The `s6lockd` program