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