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