diff options
Diffstat (limited to 'doc/libstddjb/selfpipe.html')
| -rw-r--r-- | doc/libstddjb/selfpipe.html | 40 |
1 files changed, 18 insertions, 22 deletions
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. </p> -<h3> Trapping/untrapping signals </h3> +<h3> Trapping signals </h3> <pre> int r = selfpipe_trap(SIGTERM) ; @@ -140,24 +140,14 @@ int r = selfpipe_trap(SIGTERM) ; <p> <tt>selfpipe_trap()</tt> catches a signal and sends it to the selfpipe. -Uncaught signals won't trigger the selfpipe. <tt>r</tt> is 0 if -the operation succeeded, and -1 if it failed. If it succeeded, you +Uncaught signals won't trigger the selfpipe. <tt>r</tt> is 1 if +the operation succeeded, and 0 if it failed. If it succeeded, you can forget about the trapped signal entirely. <br /> -In our example, if <tt>r</tt> is 0, then a SIGTERM will instantly +In our example, if <tt>r</tt> is 1, then a SIGTERM will instantly trigger readability on <tt>fd</tt>. </p> <pre> -int r = selfpipe_untrap(SIGTERM) ; -</pre> - -<p> -Conversely, <tt>selfpipe_untrap()</tt> uncatches a signal; the selfpipe -will not manage it anymore. <tt>r</tt> is 0 if the operation succeeded -and -1 if it failed. -</p> - -<pre> int r ; sigset_t set ; sigemptyset(&set) ; @@ -167,12 +157,12 @@ r = selfpipe_trapset(&set) ; </pre> <p> -<tt>selfpipe_trap()</tt> and <tt>selfpipe_untrap()</tt> handle signals one +<tt>selfpipe_trap()</tt> handles signals one by one. Alternatively (and often preferrably), you can use <tt>selfpipe_trapset()</tt> to directly handle signal sets. When you call <tt>selfpipe_trapset()</tt>, signals that are present in <tt>set</tt> will be caught by the selfpipe, and signals that are absent from <tt>set</tt> -will be uncaught. <tt>r</tt> is 0 if the operation succeeded and -1 if it +will be uncaught. <tt>r</tt> is 1 if the operation succeeded and 0 if it failed. </p> @@ -200,7 +190,8 @@ selfpipe_finish() ; <p> Call <tt>selfpipe_finish()</tt> 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. </p> <h2> Any limitations ? </h2> @@ -211,11 +202,16 @@ Signal handlers will be restored to their previous value. <ul> <li> 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. </li> +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 <a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_sigmask.html">pthread_sigmask()</a>) +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 +<a href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/poll.html">poll()</a> +or <a href="iopause.html">iopause()</a>) so you can just add the selfpipe +to the list of fds you're reading on. </li> <li> In rare cases, the self-pipe can theoretically be filled, if some application sends more than PIPE_BUF signals before you have time to <tt>selfpipe_read()</tt>. On most Unix systems, PIPE_BUF is 4096, |