sigchain: move doc to sigchain.h
Move the documentation from Documentation/technical/api-sigchain.txt to sigchain.h as it's easier for the developers to find the usage information beside the code instead of looking for it in another doc file. Also documentation/technical/api-sigchain.txt is removed because the information it has is now redundant and it'll be hard to keep it up to date and synchronized with the documentation in the header file. Signed-off-by: Heba Waly <heba.waly@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Heba Waly committed
Nov 17, 2019 at 21:04 UTC
c0be43f8986b1653cb4c401e288f38b1b5d595de
2 files changed
+45
-41
Documentation/technical/api-sigchain.txt
deleted
-41
@@ -1,41 +0,0 @@
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 typedef 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.
sigchain.h
+45
@@ -1,12 +1,57 @@
1
#ifndef SIGCHAIN_H
2
#define SIGCHAIN_H
3
4
+/**
5
+ * Code often wants to set a signal handler to clean up temporary files or
6
+ * other work-in-progress when we die unexpectedly. For multiple pieces of
7
+ * code to do this without conflicting, each piece of code must remember
8
+ * the old value of the handler and restore it either when:
9
+ *
10
+ * 1. The work-in-progress is finished, and the handler is no longer
11
+ * necessary. The handler should revert to the original behavior
12
+ * (either another handler, SIG_DFL, or SIG_IGN).
13
+ *
14
+ * 2. The signal is received. We should then do our cleanup, then chain
15
+ * to the next handler (or die if it is SIG_DFL).
16
+ *
17
+ * Sigchain is a tiny library for keeping a stack of handlers. Your handler
18
+ * and installation code should look something like:
19
+ *
20
+ * ------------------------------------------
21
+ * void clean_foo_on_signal(int sig)
22
+ * {
23
+ * clean_foo();
24
+ * sigchain_pop(sig);
25
+ * raise(sig);
26
+ * }
27
+ *
28
+ * void other_func()
29
+ * {
30
+ * sigchain_push_common(clean_foo_on_signal);
31
+ * mess_up_foo();
32
+ * clean_foo();
33
+ * }
34
+ * ------------------------------------------
35
+ *
36
+ */
37
+
38
+/**
39
+ * Handlers are given the typedef of sigchain_fun. This is the same type
40
+ * that is given to signal() or sigaction(). It is perfectly reasonable to
41
+ * push SIG_DFL or SIG_IGN onto the stack.
42
+ */
43
typedef void (*sigchain_fun)(int);
44
45
+/* You can sigchain_push and sigchain_pop individual signals. */
46
int sigchain_push(int sig, sigchain_fun f);
47
int sigchain_pop(int sig);
48
49
+/**
50
+ * push the handler onto the stack for the common signals:
51
+ * SIGINT, SIGHUP, SIGTERM, SIGQUIT and SIGPIPE.
52
+ */
53
void sigchain_push_common(sigchain_fun f);
54
+
55
void sigchain_pop_common(void);
56
57
#endif /* SIGCHAIN_H */