Add explanation of the signal delaying

Author: Frizlab

Readme.adoc

@@ -42,3 +42,81 @@ Handling signal SIGTERM from sigaction
 ----
 
 == How Does Delaying the Sigaction Work?
+
+Delaying a signal is an unusual process and you should be aware of the inner
+workings of this method before using it.
+
+We have two delaying strategies. One sets the signal as ignored until the signal
+is allowed to go through (`SigactionDelayer_Unsig`); the other blocks the
+incoming signal until the signal is allowed to go through
+(`SigactionDelayer_Block`).
+
+Both strategies have pros and cons.
+
+While the signal is blocked or ignored, it is also monitored using `libdispatch`
+(aka. GCD), which itself monitors the signals using `kqueue` on BSD and
+`signalfd` on Linux. This allows unblocking the signal or setting the sigaction
+handler when needed.
+
+**Important caveat of both methods**: `libdispatch` can only detect signals sent
+to the whole process, not threads. A delayed signal sent to a thread is thus
+blocked or ignored forever.
+
+=== Details of the Unsigaction Strategy (`SigactionDelayer_Unsig`)
+
+This is the recommended method.
+
+This method does not require any particular bootstrap. You can delay a signal
+whenever you want.
+
+Once a signal has been registered for delay though, the sigaction should not be
+manually changed. (Exception being made of the `install` method provided by the
+`Sigaction` struct in this project, which is aware of the possible unsigactions
+on the signal and can update them accordingly.)
+
+When a signal is first registered for delay a few things happen:
+
+* The sigaction handler is saved in an internal structure;
+* The signal is set to be ignored;
+* A dedicated thread is spawned (if not already spawned), which unblocks all
+signals;
+* A dispatch source is created to monitor the incoming signal using GCD.
+
+Then, when a signal is received, this happens:
+
+* `libdispatch` notifies the sigaction delayer, which will in turn
+* Reinstall temporarily the saved sigaction for the signal (after the clients
+say it’s ok), and
+* Send the signal to the dedicated thread. This triggers the sigaction but does
+not notify `libdispatch`.
+* Finally, the delayer sets the signal back to being ignored.
+
+**Caveats of this method**:
+
+* There is a non-avoidable race-condition (AFAICT) between the time the signal
+is sent and set back to ignored;
+* The signal that is sent back has lost the siginfo of the original signal.
+
+=== Details of the Blocking Strategy (`SigactionDelayer_Block`)
+
+You must bootstrap this method before using it, giving the bootstrap method all
+the signals you’ll want to delay, _before any threads are created_.
+The bootstrap will first block all the given signals on the current (main)
+thread, then spawn a thread on which all these signals will be unblocked.
+
+This allows our dedicated thread to be the only one allowed to receive the
+signals that are to be monitored.
+
+When a signal is registered for delay, the delayer will block the signal on the
+dedicated thread too!
+
+When the signal is received, `libdispatch` will notify the delayer, which will
+unblock the signal, thus allowing it to be delivered.
+
+**Caveat of this method**: On macOS, when a signal blocked on all threads is
+received, it seems to be affected to an arbitrary thread. Unblocking the signal
+on another thread will not unblock it at all. To workaround this problem we
+check if the signal is pending on the dedicated thread before unblocking it. If
+it is not, we send the signal to our thread, thus losing the sigaction again,
+exactly like when using the unsigaction strategy. Plus the original signal will
+stay pending on the affected thread forever.