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/selfpipe.html | 40 ++++++++++++++++++---------------------- 1 file changed, 18 insertions(+), 22 deletions(-) (limited to 'doc/libstddjb/selfpipe.html') 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.3.1