document sigchain api
It's pretty straightforward, but a stripped-down example never hurts. And we should make clear that it is explicitly OK to use SIG_DFL and SIG_IGN. Signed-off-by: Jeff King <peff@peff.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jeff King committed
Nov 11, 2010 at 23:24 UTC
ed296fe88dc8790f25a3546f1688dd40f8cbf2d1
1 file changed
+41
Documentation/technical/api-sigchain.txt
new
+41
@@ -0,0 +1,41 @@
1
+sigchain API
2
+============
3
+
4
+Code often wants to set a signal handler to clean up temporary files or
5
+other work-in-progress when we die unexpectedly. For multiple pieces of
6
+code to do this without conflicting, each piece of code must remember
7
+the old value of the handler and restore it either when:
8
+
9
+ 1. The work-in-progress is finished, and the handler is no longer
10
+ necessary. The handler should revert to the original behavior
11
+ (either another handler, SIG_DFL, or SIG_IGN).
12
+
13
+ 2. The signal is received. We should then do our cleanup, then chain
14
+ to the next handler (or die if it is SIG_DFL).
15
+
16
+Sigchain is a tiny library for keeping a stack of handlers. Your handler
17
+and installation code should look something like:
18
+
19
+------------------------------------------
20
+ void clean_foo_on_signal(int sig)
21
+ {
22
+ clean_foo();
23
+ sigchain_pop(sig);
24
+ raise(sig);
25
+ }
26
+
27
+ void other_func()
28
+ {
29
+ sigchain_push_common(clean_foo_on_signal);
30
+ mess_up_foo();
31
+ clean_foo();
32
+ }
33
+------------------------------------------
34
+
35
+Handlers are given the typdef of sigchain_fun. This is the same type
36
+that is given to signal() or sigaction(). It is perfectly reasonable to
37
+push SIG_DFL or SIG_IGN onto the stack.
38
+
39
+You can sigchain_push and sigchain_pop individual signals. For
40
+convenience, sigchain_push_common will push the handler onto the stack
41
+for many common signals.