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