]>
Commit | Line | Data |
---|---|---|
acddc0ed | 1 | // SPDX-License-Identifier: ISC |
a5b38c5b DL |
2 | /* |
3 | * Copyright (c) 2016 David Lamparter, for NetDEF, Inc. | |
a5b38c5b DL |
4 | */ |
5 | ||
6 | #ifndef _FRR_HOOK_H | |
7 | #define _FRR_HOOK_H | |
8 | ||
9 | #include <stdbool.h> | |
10 | ||
11 | #include "module.h" | |
12 | #include "memory.h" | |
13 | ||
5e244469 RW |
14 | #ifdef __cplusplus |
15 | extern "C" { | |
16 | #endif | |
17 | ||
a5b38c5b DL |
18 | /* type-safe subscribable hook points |
19 | * | |
20 | * where "type-safe" applies to the function pointers used for subscriptions | |
21 | * | |
22 | * overall usage: | |
23 | * - to create a hook: | |
24 | * | |
25 | * mydaemon.h: | |
26 | * #include "hook.h" | |
8451921b | 27 | * DECLARE_HOOK (some_update_event, (struct eventinfo *info), (info)); |
a5b38c5b DL |
28 | * |
29 | * mydaemon.c: | |
8451921b | 30 | * DEFINE_HOOK (some_update_event, (struct eventinfo *info), (info)); |
a5b38c5b DL |
31 | * ... |
32 | * hook_call (some_update_event, info) | |
33 | * | |
34 | * Note: the second and third macro args must be the hook function's | |
35 | * parameter list, with the same names for each parameter. The second | |
36 | * macro arg is with types (used for defining things), the third arg is | |
37 | * just the names (used for passing along parameters). | |
38 | * | |
39 | * Do not use parameter names starting with "hook", these can collide with | |
40 | * names used by the hook code itself. | |
41 | * | |
42 | * The return value is always "int" for now; hook_call will sum up the | |
43 | * return values from each registered user. Default is 0. | |
44 | * | |
45 | * There are no pre-defined semantics for the value, in most cases it is | |
46 | * ignored. For success/failure indication, 0 should be success, and | |
47 | * handlers should make sure to only return 0 or 1 (not -1 or other values). | |
48 | * | |
49 | * | |
50 | * - to use a hook / create a handler: | |
51 | * | |
52 | * #include "mydaemon.h" | |
53 | * int event_handler (struct eventinfo *info) { ... } | |
54 | * hook_register (some_update_event, event_handler); | |
55 | * | |
56 | * or, if you need an argument to be passed along (addonptr will be added | |
57 | * as first argument when calling the handler): | |
58 | * | |
59 | * #include "mydaemon.h" | |
60 | * int event_handler (void *addonptr, struct eventinfo *info) { ... } | |
61 | * hook_register_arg (some_update_event, event_handler, addonptr); | |
62 | * | |
63 | * (addonptr isn't typesafe, but that should be manageable.) | |
08c4c73b DL |
64 | * |
65 | * Hooks also support a "priority" value for ordering registered calls | |
66 | * relative to each other. The priority is a signed integer where lower | |
67 | * values are called earlier. There is also "Koohs", which is hooks with | |
68 | * reverse priority ordering (for cleanup/deinit hooks, so you can use the | |
69 | * same priority value). | |
70 | * | |
71 | * Recommended priority value ranges are: | |
72 | * | |
73 | * -999 ... 0 ... 999 - main executable / daemon, or library | |
74 | * -1999 ... -1000 - modules registering calls that should run before | |
75 | * the daemon's bits | |
76 | * 1000 ... 1999 - modules calls that should run after daemon's | |
77 | * | |
78 | * Note: the default value is 1000, based on the following 2 expectations: | |
79 | * - most hook_register() usage will be in loadable modules | |
80 | * - usage of hook_register() in the daemon itself may need relative ordering | |
81 | * to itself, making an explicit value the expected case | |
82 | * | |
83 | * The priority value is passed as extra argument on hook_register_prio() / | |
84 | * hook_register_arg_prio(). Whether a hook runs in reverse is determined | |
85 | * solely by the code defining / calling the hook. (DECLARE_KOOH is actually | |
86 | * the same thing as DECLARE_HOOK, it's just there to make it obvious.) | |
a5b38c5b DL |
87 | */ |
88 | ||
89 | /* TODO: | |
90 | * - hook_unregister_all_module() | |
91 | * - introspection / CLI / debug | |
92 | * - testcases ;) | |
93 | * | |
94 | * For loadable modules, the idea is that hooks could be automatically | |
95 | * unregistered when a module is unloaded. | |
96 | * | |
97 | * It's also possible to add a constructor (MTYPE style) to DEFINE_HOOK, | |
98 | * which would make it possible for the CLI to show all hooks and all | |
99 | * registered handlers. | |
100 | */ | |
101 | ||
102 | struct hookent { | |
103 | struct hookent *next; | |
d62a17ae | 104 | void *hookfn; /* actually a function pointer */ |
a5b38c5b | 105 | void *hookarg; |
8d0a2918 DL |
106 | bool has_arg : 1; |
107 | bool ent_on_heap : 1; | |
108 | bool ent_used : 1; | |
08c4c73b | 109 | int priority; |
a5b38c5b DL |
110 | struct frrmod_runtime *module; |
111 | const char *fnname; | |
112 | }; | |
113 | ||
114 | struct hook { | |
115 | const char *name; | |
116 | struct hookent *entries; | |
08c4c73b | 117 | bool reverse; |
a5b38c5b DL |
118 | }; |
119 | ||
08c4c73b DL |
120 | #define HOOK_DEFAULT_PRIORITY 1000 |
121 | ||
a5b38c5b DL |
122 | /* subscribe/add callback function to a hook |
123 | * | |
124 | * always use hook_register(), which uses the static inline helper from | |
125 | * DECLARE_HOOK in order to get type safety | |
126 | */ | |
8d0a2918 DL |
127 | extern void _hook_register(struct hook *hook, struct hookent *stackent, |
128 | void *funcptr, void *arg, bool has_arg, | |
129 | struct frrmod_runtime *module, | |
08c4c73b | 130 | const char *funcname, int priority); |
8d0a2918 DL |
131 | |
132 | /* most hook_register calls are not in a loop or similar and can use a | |
133 | * statically allocated "struct hookent" from the data segment | |
134 | */ | |
135 | #define _hook_reg_svar(hook, funcptr, arg, has_arg, module, funcname, prio) \ | |
136 | do { \ | |
e01a788c | 137 | static struct hookent stack_hookent = {}; \ |
8d0a2918 DL |
138 | _hook_register(hook, &stack_hookent, funcptr, arg, has_arg, \ |
139 | module, funcname, prio); \ | |
140 | } while (0) | |
141 | ||
d62a17ae | 142 | #define hook_register(hookname, func) \ |
8d0a2918 | 143 | _hook_reg_svar(&_hook_##hookname, _hook_typecheck_##hookname(func), \ |
08c4c73b | 144 | NULL, false, THIS_MODULE, #func, HOOK_DEFAULT_PRIORITY) |
d62a17ae | 145 | #define hook_register_arg(hookname, func, arg) \ |
8d0a2918 | 146 | _hook_reg_svar(&_hook_##hookname, \ |
d62a17ae | 147 | _hook_typecheck_arg_##hookname(func), arg, true, \ |
08c4c73b DL |
148 | THIS_MODULE, #func, HOOK_DEFAULT_PRIORITY) |
149 | #define hook_register_prio(hookname, prio, func) \ | |
8d0a2918 | 150 | _hook_reg_svar(&_hook_##hookname, _hook_typecheck_##hookname(func), \ |
08c4c73b DL |
151 | NULL, false, THIS_MODULE, #func, prio) |
152 | #define hook_register_arg_prio(hookname, prio, func, arg) \ | |
8d0a2918 | 153 | _hook_reg_svar(&_hook_##hookname, \ |
996c9314 LB |
154 | _hook_typecheck_arg_##hookname(func), arg, true, \ |
155 | THIS_MODULE, #func, prio) | |
a5b38c5b DL |
156 | |
157 | extern void _hook_unregister(struct hook *hook, void *funcptr, void *arg, | |
158 | bool has_arg); | |
d62a17ae | 159 | #define hook_unregister(hookname, func) \ |
160 | _hook_unregister(&_hook_##hookname, _hook_typecheck_##hookname(func), \ | |
161 | NULL, false) | |
162 | #define hook_unregister_arg(hookname, func, arg) \ | |
163 | _hook_unregister(&_hook_##hookname, \ | |
164 | _hook_typecheck_arg_##hookname(func), arg, true) | |
a5b38c5b DL |
165 | |
166 | /* invoke hooks | |
167 | * this is private (static) to the file that has the DEFINE_HOOK statement | |
168 | */ | |
d62a17ae | 169 | #define hook_call(hookname, ...) hook_call_##hookname(__VA_ARGS__) |
a5b38c5b DL |
170 | |
171 | /* helpers to add the void * arg */ | |
172 | #define HOOK_ADDDEF(...) (void *hookarg , ## __VA_ARGS__) | |
173 | #define HOOK_ADDARG(...) (hookarg , ## __VA_ARGS__) | |
174 | ||
14040553 DL |
175 | /* and another helper to convert () into (void) to get a proper prototype */ |
176 | #define _SKIP_10(x0, x1, x2, x3, x4, x5, x6, x7, x8, x9, ret, ...) ret | |
177 | #define _MAKE_VOID(...) _SKIP_10(, ##__VA_ARGS__, , , , , , , , , , void) | |
178 | ||
179 | #define HOOK_VOIDIFY(...) (_MAKE_VOID(__VA_ARGS__) __VA_ARGS__) | |
180 | ||
a5b38c5b | 181 | /* use in header file - declares the hook and its arguments |
8451921b | 182 | * usage: DECLARE_HOOK(my_hook, (int arg1, struct foo *arg2), (arg1, arg2)); |
a5b38c5b DL |
183 | * as above, "passlist" must use the same order and same names as "arglist" |
184 | * | |
214d8a60 | 185 | * theoretically passlist is not necessary, but let's keep things simple and |
a5b38c5b DL |
186 | * use exact same args on DECLARE and DEFINE. |
187 | */ | |
d62a17ae | 188 | #define DECLARE_HOOK(hookname, arglist, passlist) \ |
189 | extern struct hook _hook_##hookname; \ | |
14040553 DL |
190 | __attribute__((unused)) static inline void * \ |
191 | _hook_typecheck_##hookname(int(*funcptr) HOOK_VOIDIFY arglist) \ | |
d62a17ae | 192 | { \ |
193 | return (void *)funcptr; \ | |
194 | } \ | |
14040553 DL |
195 | __attribute__((unused)) static inline void \ |
196 | *_hook_typecheck_arg_##hookname(int(*funcptr) \ | |
197 | HOOK_ADDDEF arglist) \ | |
d62a17ae | 198 | { \ |
199 | return (void *)funcptr; \ | |
8451921b DL |
200 | } \ |
201 | MACRO_REQUIRE_SEMICOLON() /* end */ | |
202 | ||
996c9314 | 203 | #define DECLARE_KOOH(hookname, arglist, passlist) \ |
08c4c73b | 204 | DECLARE_HOOK(hookname, arglist, passlist) |
a5b38c5b DL |
205 | |
206 | /* use in source file - contains hook-related definitions. | |
207 | */ | |
08c4c73b | 208 | #define DEFINE_HOOK_INT(hookname, arglist, passlist, rev) \ |
d62a17ae | 209 | struct hook _hook_##hookname = { \ |
08c4c73b | 210 | .name = #hookname, .entries = NULL, .reverse = rev, \ |
d62a17ae | 211 | }; \ |
14040553 | 212 | static int hook_call_##hookname HOOK_VOIDIFY arglist \ |
d62a17ae | 213 | { \ |
214 | int hooksum = 0; \ | |
215 | struct hookent *he = _hook_##hookname.entries; \ | |
216 | void *hookarg; \ | |
217 | union { \ | |
218 | void *voidptr; \ | |
14040553 | 219 | int(*fptr) HOOK_VOIDIFY arglist; \ |
d62a17ae | 220 | int(*farg) HOOK_ADDDEF arglist; \ |
221 | } hookp; \ | |
222 | for (; he; he = he->next) { \ | |
223 | hookarg = he->hookarg; \ | |
224 | hookp.voidptr = he->hookfn; \ | |
225 | if (!he->has_arg) \ | |
226 | hooksum += hookp.fptr passlist; \ | |
227 | else \ | |
228 | hooksum += hookp.farg HOOK_ADDARG passlist; \ | |
229 | } \ | |
230 | return hooksum; \ | |
8451921b DL |
231 | } \ |
232 | MACRO_REQUIRE_SEMICOLON() /* end */ | |
a5b38c5b | 233 | |
996c9314 | 234 | #define DEFINE_HOOK(hookname, arglist, passlist) \ |
08c4c73b | 235 | DEFINE_HOOK_INT(hookname, arglist, passlist, false) |
996c9314 | 236 | #define DEFINE_KOOH(hookname, arglist, passlist) \ |
08c4c73b DL |
237 | DEFINE_HOOK_INT(hookname, arglist, passlist, true) |
238 | ||
5e244469 RW |
239 | #ifdef __cplusplus |
240 | } | |
241 | #endif | |
242 | ||
a5b38c5b | 243 | #endif /* _FRR_HOOK_H */ |