From 2da0223d5d1e91a7154996969ce44f48d9838a4f Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 29 Sep 2021 13:45:39 +0000 Subject: Doc fixes Signed-off-by: Laurent Bercot --- doc/libstddjb/cdb.html | 105 +++++++++++++++++++++++++++++++++++++++++++- doc/libstddjb/selfpipe.html | 40 ++++++++--------- 2 files changed, 122 insertions(+), 23 deletions(-) diff --git a/doc/libstddjb/cdb.html b/doc/libstddjb/cdb.html index 40a2c41..8d72b9e 100644 --- a/doc/libstddjb/cdb.html +++ b/doc/libstddjb/cdb.html @@ -20,8 +20,111 @@

The skalibs/cdb.h header

+

General information

+ +

+ A cdb, for constant database, +is an immutable key-value store. In skalibs, a cdb is built once via the +cdbmake primitives and stored on disk; the cdb +primitives, documented here, are about accessing the information. +

+ +

Data structures

+ + + +

Macros and functions

+ +

Starting and ending

+ +

+ int cdb_init (cdb *c, char const *file)
+Maps the file named file to the cdb pointed to by c. +*c must be CDB_ZERO before the call. The function returns a +positive integer if it succeeds, and 0 (and sets errno) if it fails. +

+ +

+ int cdb_init_at (cdb *c, int dfd, char const *file)
+Like cdb_init, but file is interpreted relative to the +file descriptor dfd, which must be open on a directory. +

+ +

+ int cdb_init_fromfd (cdb *c, int fd)
+Like cdb_init, but the database file is already open and +readable via then file descriptor fd. +

+ +

+ void cdb_free (cdb *c)
+Frees the resources used by a cdb mapping. After the call, c +is immediately reusable by another cdb_init function. +

+ +

cdb lookup

+ +

Single record lookup

+ +

+ int cdb_find (cdb const *c, cdb_data *data, char const *key, uint32_t klen)
+Looks up key key of length klen in the cdb *c. The function returns +-1 if *c isn't a valid cdb; 0 if no record can be found for the key; and 1 on success, in +which case the corresponding value is returned in *data: data→s +points to the start of the value, and data→len contains the length of +the value. Only the first record with the same key can be obtained this way. +

+ +

Multiple record lookup

+ +

+ void cdb_findstart (cdb_find_state *state)
+Initializes state so that the next invocation of cdb_findnext() +finds the first record for a given key. +

+ +

+ int cdb_findnext (cdb const *c, cdb_data *data, char const *key, uint32_t klen, cdb_find_state *state)
+Like cdb_find, except that the extra argument state memorizes +internal cdb lookup data, so the next cdb_findnext() invocation with the +same key, klen and state will yield the next record +for the key. cdb_findnext returns 0 when all the records for the key have +been exhausted. +

+ +

cdb enumeration

+ +

+ void cdb_traverse_init (uint32_t *pos)
+Initializes *pos so that the next invocation of cdb_traverse_next +finds the first entry in the cdb. *pos can also be initialized to the +macro CDB_TRAVERSE_INIT() instead. +

+

- TODO: write this documentation page. (Sorry!) + int cdb_traverse_next (cdb const *c, cdb_data *key, cdb_data *data, uint32_t *pos)
+Gets the next entry in the cdb *c. On success, the key is stored in *key and the +data is stored in *data. *pos* is an opaque integer storing internal +state; it is automatically updated so that the next invocation of cdb_traverse_next() +yields the next entry. The function returns -1 if *c is not a valid cdb or *pos +is not valid state, 1 on success, and 0 if no entry can be found, i.e. the end of the cdb has +been reached.

diff --git a/doc/libstddjb/selfpipe.html b/doc/libstddjb/selfpipe.html index 966c34d..1a04c74 100644 --- a/doc/libstddjb/selfpipe.html +++ b/doc/libstddjb/selfpipe.html @@ -132,7 +132,7 @@ non-blocking descriptor that can be used in your event loop. It will be selected for readability when you've caught a signal.

-

Trapping/untrapping signals

+

Trapping signals 

 int r = selfpipe_trap(SIGTERM) ;
@@ -140,23 +140,13 @@ int r = selfpipe_trap(SIGTERM) ;
 
 

 selfpipe_trap() catches a signal and sends it to the selfpipe.
-Uncaught signals won't trigger the selfpipe. r is 0 if
-the operation succeeded, and -1 if it failed. If it succeeded, you
+Uncaught signals won't trigger the selfpipe. r is 1 if
+the operation succeeded, and 0 if it failed. If it succeeded, you
 can forget about the trapped signal entirely. 

-In our example, if r is 0, then a SIGTERM will instantly
+In our example, if r is 1, then a SIGTERM will instantly
 trigger readability on fd.
 

 
-
-int r = selfpipe_untrap(SIGTERM) ;
-

-
-

-Conversely, selfpipe_untrap() uncatches a signal; the selfpipe
-will not manage it anymore. r is 0 if the operation succeeded
-and -1 if it failed.
-

-
 
 int r ;
 sigset_t set ;
@@ -167,12 +157,12 @@ r = selfpipe_trapset(&set) ;
 

 
 

-selfpipe_trap() and selfpipe_untrap() handle signals one
+selfpipe_trap() handles signals one
 by one. Alternatively (and often preferrably), you can use
 selfpipe_trapset() to directly handle signal sets. When you call
 selfpipe_trapset(), signals that are present in set will
 be caught by the selfpipe, and signals that are absent from set
-will be uncaught. r is 0 if the operation succeeded and -1 if it
+will be uncaught. r is 1 if the operation succeeded and 0 if it
 failed.
 

 
@@ -200,7 +190,8 @@ selfpipe_finish() ;
 
 

  Call selfpipe_finish() when you're done using the selfpipe.
-Signal handlers will be restored to their previous value.
+Signal handlers will be restored to SIG_DFL, i.e. signals will not
+be trapped anymore.
 

 
 
 Any limitations ? 

@@ -211,11 +202,16 @@ Signal handlers will be restored to their previous value.
 
 
    
  
  •  The selfpipe library uses a global pipe;
-so, it's not safe for multithreading. I'm not sure how multithreaded
-programs handle signals; I personally don't like multithreading and
-never use it, so I'm not knowledgeable about it. Anyway, if your
-program is multithreaded, chances are you don't have an asynchronous
-event loop, so the self-pipe trick has less benefits for you. 
    • 
+so, it's theoretically not safe for multithreading. However, as long as you dedicate
+one thread to signal handling and block signals in all the other threads
+(see pthread_sigmask())
+then you should be able to use the selfpipe in the thread that handles
+signals without trouble. Since reading the selfpipe involves waiting for
+a file descriptor to become readable, it is recommended to do this in a
+thread that will already have a regular input/output loop (via
+poll()
+or iopause()) so you can just add the selfpipe
+to the list of fds you're reading on. 
  
  •  In rare cases, the self-pipe can theoretically be filled, if some
 application sends more than PIPE_BUF signals before you have time to
 selfpipe_read(). On most Unix systems, PIPE_BUF is 4096,
-- 
cgit v1.2.3