BadVPN – Blame information for rev 1
?pathlinks?
Rev | Author | Line No. | Line |
---|---|---|---|
1 | office | 1 | /** |
2 | * @file NCDModule.h |
||
3 | * @author Ambroz Bizjak <ambrop7@gmail.com> |
||
4 | * |
||
5 | * @section LICENSE |
||
6 | * |
||
7 | * Redistribution and use in source and binary forms, with or without |
||
8 | * modification, are permitted provided that the following conditions are met: |
||
9 | * 1. Redistributions of source code must retain the above copyright |
||
10 | * notice, this list of conditions and the following disclaimer. |
||
11 | * 2. Redistributions in binary form must reproduce the above copyright |
||
12 | * notice, this list of conditions and the following disclaimer in the |
||
13 | * documentation and/or other materials provided with the distribution. |
||
14 | * 3. Neither the name of the author nor the |
||
15 | * names of its contributors may be used to endorse or promote products |
||
16 | * derived from this software without specific prior written permission. |
||
17 | * |
||
18 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND |
||
19 | * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED |
||
20 | * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE |
||
21 | * DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY |
||
22 | * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES |
||
23 | * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; |
||
24 | * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND |
||
25 | * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
||
26 | * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
||
27 | * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
||
28 | */ |
||
29 | |||
30 | #ifndef BADVPN_NCD_NCDMODULE_H |
||
31 | #define BADVPN_NCD_NCDMODULE_H |
||
32 | |||
33 | #include <stdarg.h> |
||
34 | |||
35 | #include <misc/debug.h> |
||
36 | #include <system/BReactor.h> |
||
37 | #include <base/BLog.h> |
||
38 | #include <ncd/NCDVal.h> |
||
39 | #include <ncd/NCDObject.h> |
||
40 | #include <ncd/NCDStringIndex.h> |
||
41 | |||
42 | #ifndef BADVPN_NO_PROCESS |
||
43 | #include <system/BProcess.h> |
||
44 | #endif |
||
45 | #ifndef BADVPN_NO_UDEV |
||
46 | #include <udevmonitor/NCDUdevManager.h> |
||
47 | #endif |
||
48 | #ifndef BADVPN_NO_RANDOM |
||
49 | #include <random/BRandom2.h> |
||
50 | #endif |
||
51 | |||
52 | #define NCDMODULE_EVENT_UP 1 |
||
53 | #define NCDMODULE_EVENT_DOWN 2 |
||
54 | #define NCDMODULE_EVENT_DOWNUP 3 |
||
55 | #define NCDMODULE_EVENT_DEAD 4 |
||
56 | #define NCDMODULE_EVENT_DEADERROR 5 |
||
57 | |||
58 | struct NCDModuleInst_s; |
||
59 | struct NCDModuleProcess_s; |
||
60 | struct NCDModuleGroup; |
||
61 | struct NCDInterpModule; |
||
62 | struct NCDInterpModuleGroup; |
||
63 | struct NCDCall_interp_shared; |
||
64 | struct NCDInterpFunction; |
||
65 | |||
66 | /** |
||
67 | * Function called to inform the interpeter of state changes of the |
||
68 | * module instance. |
||
69 | * Possible events are: |
||
70 | * |
||
71 | * - NCDMODULE_EVENT_UP: the instance came up. |
||
72 | * The instance was in down state. |
||
73 | * The instance enters up state. |
||
74 | * |
||
75 | * - NCDMODULE_EVENT_DOWN: the instance went down. |
||
76 | * The instance was in up state. |
||
77 | * The instance enters down state. |
||
78 | * |
||
79 | * After the instance goes down, the interpreter should eventually call |
||
80 | * {@link NCDModuleInst_Clean} or {@link NCDModuleInst_Die}, unless |
||
81 | * the module goes up again. |
||
82 | * |
||
83 | * - NCDMODULE_EVENT_DEAD: the module died. To determine if the module |
||
84 | * died with error, read the is_error member of {@link NCDModuleInst}. |
||
85 | * The instance enters dead state. |
||
86 | * |
||
87 | * This function is not being called in event context. The interpreter should |
||
88 | * only update its internal state, and visibly react only via jobs that it pushes |
||
89 | * from within this function. The only exception is that it may free the |
||
90 | * instance from within the NCDMODULE_EVENT_DEAD event. |
||
91 | * |
||
92 | * @param inst the module instance |
||
93 | * @param event event number |
||
94 | */ |
||
95 | typedef void (*NCDModuleInst_func_event) (struct NCDModuleInst_s *inst, int event); |
||
96 | |||
97 | /** |
||
98 | * Function called when the module instance wants the interpreter to |
||
99 | * resolve an object from the point of view of its statement. |
||
100 | * The instance will not be in dead state. |
||
101 | * This function must not have any side effects. |
||
102 | * |
||
103 | * @param inst the module instance |
||
104 | * @param name name of the object as an {@link NCDStringIndex} identifier |
||
105 | * @param out_object the object will be returned here |
||
106 | * @return 1 on success, 0 on failure |
||
107 | */ |
||
108 | typedef int (*NCDModuleInst_func_getobj) (struct NCDModuleInst_s *inst, NCD_string_id_t name, NCDObject *out_object); |
||
109 | |||
110 | /** |
||
111 | * Function called when the module instance wants the interpreter to |
||
112 | * create a new process backend from a process template. |
||
113 | * The instance will not be in dead state. |
||
114 | * |
||
115 | * On success, the interpreter must have called {@link NCDModuleProcess_Interp_SetHandlers} |
||
116 | * from within this function, to allow communication with the controller of the process. |
||
117 | * On success, the new process backend enters down state. |
||
118 | * |
||
119 | * This function is not being called in event context. The interpreter should |
||
120 | * only update its internal state, and visibly react only via jobs that it pushes |
||
121 | * from within this function. |
||
122 | * |
||
123 | * @param user value of 'user' member of {@link NCDModuleInst_iparams} |
||
124 | * @param p handle for the new process backend |
||
125 | * @param template_name name of the template to create the process from, |
||
126 | * as an {@link NCDStringIndex} identifier |
||
127 | * @return 1 on success, 0 on failure |
||
128 | */ |
||
129 | typedef int (*NCDModuleInst_func_initprocess) (void *user, struct NCDModuleProcess_s *p, NCD_string_id_t template_name); |
||
130 | |||
131 | /** |
||
132 | * Function called when the module instance wants the interpreter to |
||
133 | * initiate termination, as if it received an external terminatio request (signal). |
||
134 | * |
||
135 | * @param user value of 'user' member of {@link NCDModuleInst_iparams} |
||
136 | * @param exit_code exit code to return the the operating system. This overrides any previously |
||
137 | * set exit code, and will be overriden by a signal to the value 1. |
||
138 | * |
||
139 | */ |
||
140 | typedef void (*NCDModuleInst_func_interp_exit) (void *user, int exit_code); |
||
141 | |||
142 | /** |
||
143 | * Function called when the module instance wants the interpreter to |
||
144 | * provide its extra command line arguments. |
||
145 | * |
||
146 | * @param user value of 'user' member of {@link NCDModuleInst_iparams} |
||
147 | * @param mem value memory to use |
||
148 | * @param out_value write value reference here on success |
||
149 | * @return 1 if available, 0 if not available. If available, but out of memory, return 1 |
||
150 | * and an invalid value. |
||
151 | */ |
||
152 | typedef int (*NCDModuleInst_func_interp_getargs) (void *user, NCDValMem *mem, NCDValRef *out_value); |
||
153 | |||
154 | /** |
||
155 | * Function called when the module instance wants the interpreter to |
||
156 | * provide its retry time. |
||
157 | * |
||
158 | * @param user value of 'user' member of {@link NCDModuleInst_iparams} |
||
159 | * @return retry time in milliseconds |
||
160 | */ |
||
161 | typedef btime_t (*NCDModuleInst_func_interp_getretrytime) (void *user); |
||
162 | |||
163 | /** |
||
164 | * Function called when the module instance wants the interpreter to |
||
165 | * load a new module group. |
||
166 | * |
||
167 | * @param user value of 'user' member of {@link NCDModuleInst_iparams} |
||
168 | * @param group module group to load |
||
169 | * @return 1 on success, 0 on failure |
||
170 | */ |
||
171 | typedef int (*NCDModuleInst_func_interp_loadgroup) (void *user, const struct NCDModuleGroup *group); |
||
172 | |||
173 | #define NCDMODULEPROCESS_EVENT_UP 1 |
||
174 | #define NCDMODULEPROCESS_EVENT_DOWN 2 |
||
175 | #define NCDMODULEPROCESS_EVENT_TERMINATED 3 |
||
176 | |||
177 | /** |
||
178 | * Handler which reports process state changes from the interpreter. |
||
179 | * Possible events are: |
||
180 | * |
||
181 | * - NCDMODULEPROCESS_EVENT_UP: the process went up. |
||
182 | * The process was in down state. |
||
183 | * The process enters up state. |
||
184 | * |
||
185 | * - NCDMODULEPROCESS_EVENT_DOWN: the process went down. |
||
186 | * The process was in up state. |
||
187 | * The process enters waiting state. |
||
188 | * |
||
189 | * NOTE: the process enters waiting state, NOT down state, and is paused. |
||
190 | * To allow the process to continue, call {@link NCDModuleProcess_Continue}. |
||
191 | * |
||
192 | * - NCDMODULEPROCESS_EVENT_TERMINATED: the process terminated. |
||
193 | * The process was in terminating state. |
||
194 | * The process enters terminated state. |
||
195 | * |
||
196 | * @param user pointer to the process. Use {@link UPPER_OBJECT} to retrieve the pointer |
||
197 | * to the containing struct. |
||
198 | * @param event event number |
||
199 | */ |
||
200 | typedef void (*NCDModuleProcess_handler_event) (struct NCDModuleProcess_s *process, int event); |
||
201 | |||
202 | /** |
||
203 | * Function called when the interpreter wants to resolve a special |
||
204 | * object in the process. |
||
205 | * This function must have no side effects. |
||
206 | * |
||
207 | * @param user pointer to the process. Use {@link UPPER_OBJECT} to retrieve the pointer |
||
208 | * to the containing struct. |
||
209 | * @param name name of the object as an {@link NCDStringIndex} identifier |
||
210 | * @param out_object the object will be returned here |
||
211 | * @return 1 on success, 0 on failure |
||
212 | */ |
||
213 | typedef int (*NCDModuleProcess_func_getspecialobj) (struct NCDModuleProcess_s *process, NCD_string_id_t name, NCDObject *out_object); |
||
214 | |||
215 | #define NCDMODULEPROCESS_INTERP_EVENT_CONTINUE 1 |
||
216 | #define NCDMODULEPROCESS_INTERP_EVENT_TERMINATE 2 |
||
217 | |||
218 | /** |
||
219 | * Function called to report process backend requests to the interpreter. |
||
220 | * Possible events are: |
||
221 | * |
||
222 | * - NCDMODULEPROCESS_INTERP_EVENT_CONTINUE: the process can continue. |
||
223 | * The process backend was in waiting state. |
||
224 | * The process backend enters down state. |
||
225 | * |
||
226 | * - NCDMODULEPROCESS_INTERP_EVENT_TERMINATE: the process should terminate. |
||
227 | * The process backend was in down, up or waiting state. |
||
228 | * The process backend enters terminating state. |
||
229 | * |
||
230 | * The interpreter should call {@link NCDModuleProcess_Interp_Terminated} |
||
231 | * when the process terminates. |
||
232 | * |
||
233 | * This function is not being called in event context. The interpreter should |
||
234 | * only update its internal state, and visibly react only via jobs that it pushes |
||
235 | * from within this function. |
||
236 | * |
||
237 | * @param user as in {@link NCDModuleProcess_Interp_SetHandlers} |
||
238 | * @param event event number |
||
239 | */ |
||
240 | typedef void (*NCDModuleProcess_interp_func_event) (void *user, int event); |
||
241 | |||
242 | /** |
||
243 | * Function called to have the interpreter resolve an object within the process |
||
244 | * of a process backend. |
||
245 | * This function must not have any side effects. |
||
246 | * |
||
247 | * @param user as in {@link NCDModuleProcess_Interp_SetHandlers} |
||
248 | * @param name name of the object as an {@link NCDStringIndex} identifier |
||
249 | * @param out_object the object will be returned here |
||
250 | * @return 1 on success, 0 in failure |
||
251 | */ |
||
252 | typedef int (*NCDModuleProcess_interp_func_getobj) (void *user, NCD_string_id_t name, NCDObject *out_object); |
||
253 | |||
254 | struct NCDModule; |
||
255 | |||
256 | /** |
||
257 | * Contains parameters to the module initialization function |
||
258 | * ({@link NCDModule_func_new2}) that are passed indirectly. |
||
259 | */ |
||
260 | struct NCDModuleInst_new_params { |
||
261 | /** |
||
262 | * A reference to the argument list for the module instance. |
||
263 | * The reference remains valid as long as the backend instance |
||
264 | * exists. |
||
265 | */ |
||
266 | NCDValRef args; |
||
267 | |||
268 | /** |
||
269 | * If the module instance corresponds to a method-like statement, |
||
270 | * this pointer identifies the object it is being invoked with. |
||
271 | * If the object is a statement (i.e. a {@link NCDModuleInst}), then this |
||
272 | * will be the NCDModuleInst pointer, and {@link NCDModuleInst_Backend_GetUser} |
||
273 | * can be called on this to retrieve the pointer to preallocated memory for |
||
274 | * the backend instance; *unless* {@link NCDModuleInst_Backend_PassMemToMethods} |
||
275 | * was called for the object on which the method is being called, in which case |
||
276 | * this will directly point to the preallocated memory. |
||
277 | * On the other hand, if this is a method on an internal object built using |
||
278 | * only {@link NCDObject_Build} or {@link NCDObject_BuildFull}, |
||
279 | * this pointer will be whatever was passed as the "data_ptr" argument, for the |
||
280 | * first function, and as "method_user", for the latter function. |
||
281 | */ |
||
282 | void *method_user; |
||
283 | }; |
||
284 | |||
285 | /** |
||
286 | * Contains parameters to {@link NCDModuleInst_Init} that are passed indirectly. |
||
287 | * This itself only contains parameters related to communication between the |
||
288 | * backend and the creator of the module instance; other parameters are passed |
||
289 | * via the iparams member; |
||
290 | */ |
||
291 | struct NCDModuleInst_params { |
||
292 | /** |
||
293 | * Callback to report state changes. |
||
294 | */ |
||
295 | NCDModuleInst_func_event func_event; |
||
296 | /** |
||
297 | * Callback to resolve objects from the viewpoint of the instance. |
||
298 | */ |
||
299 | NCDModuleInst_func_getobj func_getobj; |
||
300 | /** |
||
301 | * Log function which appends a log prefix with {@link BLog_Append}. |
||
302 | */ |
||
303 | BLog_logfunc logfunc; |
||
304 | /** |
||
305 | * Pointer to an {@link NCDModuleInst_iparams} structure, which exposes |
||
306 | * services provided by the interpreter. |
||
307 | */ |
||
308 | const struct NCDModuleInst_iparams *iparams; |
||
309 | }; |
||
310 | |||
311 | /** |
||
312 | * Contains parameters to {@link NCDModuleInst_Init} that are passed indirectly. |
||
313 | * This only contains parameters related to services provided by the interpreter. |
||
314 | */ |
||
315 | struct NCDModuleInst_iparams { |
||
316 | /** |
||
317 | * Reactor we live in. |
||
318 | */ |
||
319 | BReactor *reactor; |
||
320 | #ifndef BADVPN_NO_PROCESS |
||
321 | /** |
||
322 | * Process manager. |
||
323 | */ |
||
324 | BProcessManager *manager; |
||
325 | #endif |
||
326 | #ifndef BADVPN_NO_UDEV |
||
327 | /** |
||
328 | * Udev manager. |
||
329 | */ |
||
330 | NCDUdevManager *umanager; |
||
331 | #endif |
||
332 | #ifndef BADVPN_NO_RANDOM |
||
333 | /** |
||
334 | * Random number generator. |
||
335 | */ |
||
336 | BRandom2 *random2; |
||
337 | #endif |
||
338 | /** |
||
339 | * String index which keeps a mapping between strings and string identifiers. |
||
340 | */ |
||
341 | NCDStringIndex *string_index; |
||
342 | /** |
||
343 | * Pointer passed to the interpreter callbacks below, for state keeping. |
||
344 | */ |
||
345 | void *user; |
||
346 | /** |
||
347 | * Callback to create a new template process. |
||
348 | */ |
||
349 | NCDModuleInst_func_initprocess func_initprocess; |
||
350 | /** |
||
351 | * Callback to request interpreter termination. |
||
352 | */ |
||
353 | NCDModuleInst_func_interp_exit func_interp_exit; |
||
354 | /** |
||
355 | * Callback to get extra command line arguments. |
||
356 | */ |
||
357 | NCDModuleInst_func_interp_getargs func_interp_getargs; |
||
358 | /** |
||
359 | * Callback to get retry time. |
||
360 | */ |
||
361 | NCDModuleInst_func_interp_getretrytime func_interp_getretrytime; |
||
362 | /** |
||
363 | * Callback to load a module group. |
||
364 | */ |
||
365 | NCDModuleInst_func_interp_loadgroup func_loadgroup; |
||
366 | }; |
||
367 | |||
368 | /** |
||
369 | * Module instance. |
||
370 | * The module instance is initialized by the interpreter by calling |
||
371 | * {@link NCDModuleInst_Init}. It is implemented by a module backend |
||
372 | * specified in a {@link NCDModule}. |
||
373 | */ |
||
374 | typedef struct NCDModuleInst_s { |
||
375 | const struct NCDInterpModule *m; |
||
376 | const struct NCDModuleInst_params *params; |
||
377 | void *mem; // not modified by NCDModuleInst (but passed to module) |
||
378 | unsigned int state:3; |
||
379 | unsigned int pass_mem_to_methods:1; |
||
380 | unsigned int istate:3; // untouched by NCDModuleInst |
||
381 | NCDPersistentObj pobj; |
||
382 | DebugObject d_obj; |
||
383 | } NCDModuleInst; |
||
384 | |||
385 | /** |
||
386 | * Weak NCDModuleInst reference. |
||
387 | */ |
||
388 | typedef struct { |
||
389 | NCDObjRef objref; |
||
390 | DebugObject d_obj; |
||
391 | } NCDModuleRef; |
||
392 | |||
393 | /** |
||
394 | * Process created from a process template on behalf of a module backend |
||
395 | * instance, implemented by the interpreter. |
||
396 | */ |
||
397 | typedef struct NCDModuleProcess_s { |
||
398 | NCDValRef args; |
||
399 | NCDModuleProcess_handler_event handler_event; |
||
400 | NCDModuleProcess_func_getspecialobj func_getspecialobj; |
||
401 | void *interp_user; |
||
402 | NCDModuleProcess_interp_func_event interp_func_event; |
||
403 | NCDModuleProcess_interp_func_getobj interp_func_getobj; |
||
404 | #ifndef NDEBUG |
||
405 | int state; |
||
406 | #endif |
||
407 | DebugObject d_obj; |
||
408 | } NCDModuleProcess; |
||
409 | |||
410 | /** |
||
411 | * Initializes an instance of an NCD module. |
||
412 | * The instance is initialized in down state. |
||
413 | * WARNING: this directly calls the module backend; expect to be called back |
||
414 | * |
||
415 | * This and other non-Backend methods are the interpreter interface. |
||
416 | * The Backend methods are the module backend interface and are documented |
||
417 | * independently with their own logical states. |
||
418 | * |
||
419 | * NOTE: the instance structure \a n should have the member 'mem' initialized |
||
420 | * to point to preallocated memory for the statement. This memory must be |
||
421 | * at least m->prealloc_size big and must be properly aligned for any object. |
||
422 | * The 'mem' pointer is never modified by NCDModuleInst, so that the interpreter |
||
423 | * can use it as outside the lifetime of NCDModuleInst. |
||
424 | * |
||
425 | * @param n the instance |
||
426 | * @param m pointer to the {@link NCDInterpModule} structure representing the module |
||
427 | * to be instantiated |
||
428 | * @param method_context a context pointer passed to the module backend, applicable to method-like |
||
429 | * statements only. This should be set to the 'user' member of the |
||
430 | * {@link NCDObject} which represents the base object for the method. |
||
431 | * The caller must ensure that the NCDObject that was used is of the type |
||
432 | * expected by the module being instanciated. |
||
433 | * @param args arguments to the module. Must be a list value. Must be available and unchanged |
||
434 | * as long as the instance exists. |
||
435 | * @param user argument to callback functions |
||
436 | * @param params more parameters, see {@link NCDModuleInst_params} |
||
437 | */ |
||
438 | void NCDModuleInst_Init (NCDModuleInst *n, const struct NCDInterpModule *m, void *method_context, NCDValRef args, const struct NCDModuleInst_params *params); |
||
439 | |||
440 | /** |
||
441 | * Frees the instance. |
||
442 | * The instance must be in dead state. |
||
443 | * |
||
444 | * @param n the instance |
||
445 | */ |
||
446 | void NCDModuleInst_Free (NCDModuleInst *n); |
||
447 | |||
448 | /** |
||
449 | * Requests the instance to die. |
||
450 | * The instance must be in down or up state. |
||
451 | * The instance enters dying state. |
||
452 | * WARNING: this directly calls the module backend; expect to be called back |
||
453 | * |
||
454 | * @param n the instance |
||
455 | */ |
||
456 | void NCDModuleInst_Die (NCDModuleInst *n); |
||
457 | |||
458 | /** |
||
459 | * Attempts to destroy the instance immediately. |
||
460 | * This function can be used to optimize destroying instances of modules which |
||
461 | * don't specify any {@link NCDModule_func_die} handler. If immediate destruction |
||
462 | * is not possible, this does nothing and returns 0; {@link NCDModuleInst_Die} |
||
463 | * should be used to destroy the instance instead. If however immediate destruction |
||
464 | * is possible, this destroys the module instance and returns 1; {@link NCDModuleInst_Free} |
||
465 | * must not be called after that. |
||
466 | * The instance must be in down or up state, as for {@link NCDModuleInst_Die}. |
||
467 | * |
||
468 | * @param n the instance |
||
469 | * @return 1 if destruction was performed, 0 if not |
||
470 | */ |
||
471 | int NCDModuleInst_TryFree (NCDModuleInst *n); |
||
472 | |||
473 | /** |
||
474 | * Informs the module that it is in a clean state to proceed. |
||
475 | * The instance must be in down state. |
||
476 | * WARNING: this directly calls the module backend; expect to be called back |
||
477 | * |
||
478 | * @param n the instance |
||
479 | */ |
||
480 | void NCDModuleInst_Clean (NCDModuleInst *n); |
||
481 | |||
482 | /** |
||
483 | * Returns an {@link NCDObject} which can be used to resolve variables and objects |
||
484 | * within this instance, as well as call its methods. The resulting object may only |
||
485 | * be used immediately, and becomes invalid when the instance is freed. |
||
486 | * |
||
487 | * @param n the instance |
||
488 | * @return an NCDObject for this instance |
||
489 | */ |
||
490 | NCDObject NCDModuleInst_Object (NCDModuleInst *n); |
||
491 | |||
492 | /** |
||
493 | * If this is called, any methods called on this object will receive the preallocated |
||
494 | * memory pointer as the object state pointer. This means that in the |
||
495 | * {@link NCDModule_func_getvar2} function which is called when a method is created, |
||
496 | * the preallocated memory should be accessed as params->method_user. |
||
497 | * By default, however, params->method_user points to the NCDModuleInst of the base |
||
498 | * object, and {@link NCDModuleInst_Backend_GetUser} is needed to retrieve the |
||
499 | * preallocated memory pointer. |
||
500 | */ |
||
501 | void NCDModuleInst_Backend_PassMemToMethods (NCDModuleInst *n); |
||
502 | |||
503 | /** |
||
504 | * Retuns the state pointer passed to handlers of a module backend instance; |
||
505 | * see {@link NCDModule_func_new2}. |
||
506 | * |
||
507 | * @param n backend instance handle |
||
508 | * @return argument passed to handlers |
||
509 | */ |
||
510 | void * NCDModuleInst_Backend_GetUser (NCDModuleInst *n); |
||
511 | |||
512 | /** |
||
513 | * Puts the backend instance into up state. |
||
514 | * The instance must be in down state. |
||
515 | * The instance enters up state. |
||
516 | * |
||
517 | * @param n backend instance handle |
||
518 | */ |
||
519 | void NCDModuleInst_Backend_Up (NCDModuleInst *n); |
||
520 | |||
521 | /** |
||
522 | * Puts the backend instance into down state. |
||
523 | * The instance must be in up state. |
||
524 | * The instance enters down state. |
||
525 | * |
||
526 | * @param n backend instance handle |
||
527 | */ |
||
528 | void NCDModuleInst_Backend_Down (NCDModuleInst *n); |
||
529 | |||
530 | /** |
||
531 | * Puts the backend instance into down state, then immediatly back into the up state. |
||
532 | * This effectively causes the interpreter to start backtracking to this statement. |
||
533 | * The instance must be in up state, and remains in up state. |
||
534 | * |
||
535 | * @param n backend instance handle |
||
536 | */ |
||
537 | void NCDModuleInst_Backend_DownUp (NCDModuleInst *n); |
||
538 | |||
539 | /** |
||
540 | * Destroys the backend instance. |
||
541 | * The backend instance handle becomes invalid and must not be used from |
||
542 | * the backend any longer. |
||
543 | * |
||
544 | * @param n backend instance handle |
||
545 | */ |
||
546 | void NCDModuleInst_Backend_Dead (NCDModuleInst *n); |
||
547 | |||
548 | /** |
||
549 | * Like {@link NCDModuleInst_Backend_Dead}, but also reports an error condition |
||
550 | * to the interpreter. |
||
551 | */ |
||
552 | void NCDModuleInst_Backend_DeadError (NCDModuleInst *n); |
||
553 | |||
554 | /** |
||
555 | * Resolves an object for a backend instance, from the point of the instance's |
||
556 | * statement in the containing process. |
||
557 | * |
||
558 | * @param n backend instance handle |
||
559 | * @param name name of the object to resolve as an {@link NCDStringIndex} identifier |
||
560 | * @param out_object the object will be returned here |
||
561 | * @return 1 on success, 0 on failure |
||
562 | */ |
||
563 | int NCDModuleInst_Backend_GetObj (NCDModuleInst *n, NCD_string_id_t name, NCDObject *out_object) WARN_UNUSED; |
||
564 | |||
565 | /** |
||
566 | * Logs a backend instance message. |
||
567 | * |
||
568 | * @param n backend instance handle |
||
569 | * @param channel log channel |
||
570 | * @param level loglevel |
||
571 | * @param fmt format string as in printf, arguments follow |
||
572 | */ |
||
573 | void NCDModuleInst_Backend_Log (NCDModuleInst *n, int channel, int level, const char *fmt, ...); |
||
574 | |||
575 | /** |
||
576 | * Like {@link NCDModuleInst_Backend_Log}, but the extra arguments are passed |
||
577 | * as a va_list. This allows creation of logging wrappers. |
||
578 | */ |
||
579 | void NCDModuleInst_Backend_LogVarArg (NCDModuleInst *n, int channel, int level, const char *fmt, va_list vl); |
||
580 | |||
581 | /** |
||
582 | * Returns a logging context. The context is valid until the backend dies. |
||
583 | */ |
||
584 | BLogContext NCDModuleInst_Backend_LogContext (NCDModuleInst *n); |
||
585 | |||
586 | /** |
||
587 | * Initiates interpreter termination. |
||
588 | * |
||
589 | * @param n backend instance handle |
||
590 | * @param exit_code exit code to return to the operating system. This overrides |
||
591 | * any previously set exit code, and will be overriden by a |
||
592 | * termination signal to the value 1. |
||
593 | */ |
||
594 | void NCDModuleInst_Backend_InterpExit (NCDModuleInst *n, int exit_code); |
||
595 | |||
596 | /** |
||
597 | * Retrieves extra command line arguments passed to the interpreter. |
||
598 | * |
||
599 | * @param n backend instance handle |
||
600 | * @param mem value memory to use |
||
601 | * @param out_value the arguments will be written here on success as a list value |
||
602 | * @return 1 if available, 0 if not available. If available, but out of memory, returns 1 |
||
603 | * and an invalid value. |
||
604 | */ |
||
605 | int NCDModuleInst_Backend_InterpGetArgs (NCDModuleInst *n, NCDValMem *mem, NCDValRef *out_value); |
||
606 | |||
607 | /** |
||
608 | * Returns the retry time of the intepreter. |
||
609 | * |
||
610 | * @param n backend instance handle |
||
611 | * @return retry time in milliseconds |
||
612 | */ |
||
613 | btime_t NCDModuleInst_Backend_InterpGetRetryTime (NCDModuleInst *n); |
||
614 | |||
615 | /** |
||
616 | * Loads a module group into the interpreter. |
||
617 | * |
||
618 | * @param n backend instance handle |
||
619 | * @param group module group to load |
||
620 | * @return 1 on success, 0 on failure |
||
621 | */ |
||
622 | int NCDModuleInst_Backend_InterpLoadGroup (NCDModuleInst *n, const struct NCDModuleGroup *group); |
||
623 | |||
624 | /** |
||
625 | * Initializes a weak reference to a module instance. |
||
626 | * The instane must no have had NCDModuleInst_Backend_PassMemToMethods |
||
627 | * called. |
||
628 | */ |
||
629 | void NCDModuleRef_Init (NCDModuleRef *o, NCDModuleInst *inst); |
||
630 | |||
631 | /** |
||
632 | * Frees the reference. |
||
633 | */ |
||
634 | void NCDModuleRef_Free (NCDModuleRef *o); |
||
635 | |||
636 | /** |
||
637 | * Dereferences the reference. |
||
638 | * If the reference was broken, returns NULL. |
||
639 | */ |
||
640 | NCDModuleInst * NCDModuleRef_Deref (NCDModuleRef *o); |
||
641 | |||
642 | /** |
||
643 | * Initializes a process in the interpreter from a process template. |
||
644 | * This must be called on behalf of a module backend instance. |
||
645 | * The process is initializes in down state. |
||
646 | * |
||
647 | * @param o the process |
||
648 | * @param n backend instance whose interpreter will be providing the process |
||
649 | * @param template_name name of the process template as an {@link NCDStringIndex} identifier |
||
650 | * @param args arguments to the process. Must be an invalid value or a list value. |
||
651 | * The value must be available and unchanged while the process exists. |
||
652 | * @param handler_event handler which reports events about the process from the |
||
653 | * interpreter |
||
654 | * @return 1 on success, 0 on failure |
||
655 | */ |
||
656 | int NCDModuleProcess_InitId (NCDModuleProcess *o, NCDModuleInst *n, NCD_string_id_t template_name, NCDValRef args, NCDModuleProcess_handler_event handler_event) WARN_UNUSED; |
||
657 | |||
658 | /** |
||
659 | * Wrapper around {@link NCDModuleProcess_InitId} which takes the template name as an |
||
660 | * {@link NCDValRef}, which must point to a string value. |
||
661 | */ |
||
662 | int NCDModuleProcess_InitValue (NCDModuleProcess *o, NCDModuleInst *n, NCDValRef template_name, NCDValRef args, NCDModuleProcess_handler_event handler_event) WARN_UNUSED; |
||
663 | |||
664 | /** |
||
665 | * Frees the process. |
||
666 | * The process must be in terminated state. |
||
667 | * |
||
668 | * @param o the process |
||
669 | */ |
||
670 | void NCDModuleProcess_Free (NCDModuleProcess *o); |
||
671 | |||
672 | /** |
||
673 | * Does nothing. |
||
674 | * The process must be in terminated state. |
||
675 | * |
||
676 | * @param o the process |
||
677 | */ |
||
678 | void NCDModuleProcess_AssertFree (NCDModuleProcess *o); |
||
679 | |||
680 | /** |
||
681 | * Sets callback functions for providing special objects within the process. |
||
682 | * |
||
683 | * @param o the process |
||
684 | * @param func_getspecialobj function for resolving special objects, or NULL |
||
685 | */ |
||
686 | void NCDModuleProcess_SetSpecialFuncs (NCDModuleProcess *o, NCDModuleProcess_func_getspecialobj func_getspecialobj); |
||
687 | |||
688 | /** |
||
689 | * Continues the process after the process went down. |
||
690 | * The process must be in waiting state. |
||
691 | * The process enters down state. |
||
692 | * |
||
693 | * @param o the process |
||
694 | */ |
||
695 | void NCDModuleProcess_Continue (NCDModuleProcess *o); |
||
696 | |||
697 | /** |
||
698 | * Requests the process to terminate. |
||
699 | * The process must be in down, up or waiting state. |
||
700 | * The process enters terminating state. |
||
701 | * |
||
702 | * @param o the process |
||
703 | */ |
||
704 | void NCDModuleProcess_Terminate (NCDModuleProcess *o); |
||
705 | |||
706 | /** |
||
707 | * Resolves an object within the process from the point |
||
708 | * at the end of the process. |
||
709 | * This function has no side effects. |
||
710 | * |
||
711 | * @param o the process |
||
712 | * @param name name of the object to resolve as an {@link NCDStringIndex} identifier |
||
713 | * @param out_object the object will be returned here |
||
714 | * @return 1 on success, 0 on failure |
||
715 | */ |
||
716 | int NCDModuleProcess_GetObj (NCDModuleProcess *o, NCD_string_id_t name, NCDObject *out_object) WARN_UNUSED; |
||
717 | |||
718 | /** |
||
719 | * Sets callback functions for the interpreter to implement the |
||
720 | * process backend. |
||
721 | * Must be called from within {@link NCDModuleInst_func_initprocess} |
||
722 | * if success is to be reported there. |
||
723 | * |
||
724 | * @param o process backend handle, as in {@link NCDModuleInst_func_initprocess} |
||
725 | * @param interp_user argument to callback functions |
||
726 | * @param interp_func_event function for reporting continue/terminate requests |
||
727 | * @param interp_func_getobj function for resolving objects within the process |
||
728 | */ |
||
729 | void NCDModuleProcess_Interp_SetHandlers (NCDModuleProcess *o, void *interp_user, |
||
730 | NCDModuleProcess_interp_func_event interp_func_event, |
||
731 | NCDModuleProcess_interp_func_getobj interp_func_getobj); |
||
732 | |||
733 | /** |
||
734 | * Reports the process backend as up. |
||
735 | * The process backend must be in down state. |
||
736 | * The process backend enters up state. |
||
737 | * WARNING: this directly calls the process creator; expect to be called back |
||
738 | * |
||
739 | * @param o process backend handle |
||
740 | */ |
||
741 | void NCDModuleProcess_Interp_Up (NCDModuleProcess *o); |
||
742 | |||
743 | /** |
||
744 | * Reports the process backend as down. |
||
745 | * The process backend must be in up state. |
||
746 | * The process backend enters waiting state. |
||
747 | * WARNING: this directly calls the process creator; expect to be called back |
||
748 | * |
||
749 | * NOTE: the backend enters waiting state, NOT down state. The interpreter should |
||
750 | * pause the process until {@link NCDModuleProcess_interp_func_event} reports |
||
751 | * NCDMODULEPROCESS_INTERP_EVENT_CONTINUE, unless termination is requested via |
||
752 | * NCDMODULEPROCESS_INTERP_EVENT_TERMINATE. |
||
753 | * |
||
754 | * @param o process backend handle |
||
755 | */ |
||
756 | void NCDModuleProcess_Interp_Down (NCDModuleProcess *o); |
||
757 | |||
758 | /** |
||
759 | * Reports termination of the process backend. |
||
760 | * The process backend must be in terminating state. |
||
761 | * The process backend handle becomes invalid and must not be used |
||
762 | * by the interpreter any longer. |
||
763 | * WARNING: this directly calls the process creator; expect to be called back |
||
764 | * |
||
765 | * @param o process backend handle |
||
766 | */ |
||
767 | void NCDModuleProcess_Interp_Terminated (NCDModuleProcess *o); |
||
768 | |||
769 | /** |
||
770 | * Resolves a special process object for the process backend. |
||
771 | * |
||
772 | * @param o process backend handle |
||
773 | * @param name name of the object as an {@link NCDStringIndex} identifier |
||
774 | * @param out_object the object will be returned here |
||
775 | * @return 1 on success, 0 on failure |
||
776 | */ |
||
777 | int NCDModuleProcess_Interp_GetSpecialObj (NCDModuleProcess *o, NCD_string_id_t name, NCDObject *out_object) WARN_UNUSED; |
||
778 | |||
779 | /** |
||
780 | * Function called before any instance of any backend in a module |
||
781 | * group is created; |
||
782 | * |
||
783 | * @param params structure containing global resources, such as |
||
784 | * {@link BReactor}, {@link BProcessManager} and {@link NCDUdevManager}. |
||
785 | * @return 1 on success, 0 on failure |
||
786 | */ |
||
787 | typedef int (*NCDModule_func_globalinit) (struct NCDInterpModuleGroup *group, const struct NCDModuleInst_iparams *params); |
||
788 | |||
789 | /** |
||
790 | * Function called to clean up after {@link NCDModule_func_globalinit} and modules |
||
791 | * in a module group. |
||
792 | * There are no backend instances alive from this module group. |
||
793 | */ |
||
794 | typedef void (*NCDModule_func_globalfree) (struct NCDInterpModuleGroup *group); |
||
795 | |||
796 | /** |
||
797 | * Handler called to create an new module backend instance. |
||
798 | * The backend is initialized in down state. |
||
799 | * |
||
800 | * If the backend fails initialization, this function should report the backend |
||
801 | * instance to have died with error by calling {@link NCDModuleInst_Backend_DeadError}. |
||
802 | * |
||
803 | * @param o if the module specifies a positive alloc_size value in the {@link NCDModule} |
||
804 | * structure, this will point to the allocated memory that can be used by the |
||
805 | * module instance while it exists. If the alloc_size is 0 (default), this may or |
||
806 | * may not be NULL. |
||
807 | * @param i module backend instance handler. The backend may only use this handle via |
||
808 | * the Backend functions of {@link NCDModuleInst}. |
||
809 | */ |
||
810 | typedef void (*NCDModule_func_new2) (void *o, NCDModuleInst *i, const struct NCDModuleInst_new_params *params); |
||
811 | |||
812 | /** |
||
813 | * Handler called to request termination of a backend instance. |
||
814 | * The backend instance was in down or up state. |
||
815 | * The backend instance enters dying state. |
||
816 | * |
||
817 | * @param o state pointer, as in {@link NCDModule_func_new2} |
||
818 | */ |
||
819 | typedef void (*NCDModule_func_die) (void *o); |
||
820 | |||
821 | /** |
||
822 | * Function called to resolve a variable within a backend instance. |
||
823 | * The backend instance is in up state, or in up or down state if can_resolve_when_down=1. |
||
824 | * This function must not have any side effects. |
||
825 | * |
||
826 | * @param o state pointer, as in {@link NCDModule_func_new2} |
||
827 | * @param name name of the variable to resolve |
||
828 | * @param mem value memory to use |
||
829 | * @param out on success, the backend should initialize the value here |
||
830 | * @return 1 if exists, 0 if not exists. If exists, but out of memory, return 1 |
||
831 | * and an invalid value. |
||
832 | */ |
||
833 | typedef int (*NCDModule_func_getvar) (void *o, const char *name, NCDValMem *mem, NCDValRef *out); |
||
834 | |||
835 | /** |
||
836 | * Function called to resolve a variable within a backend instance. |
||
837 | * The backend instance is in up state, or in up or down state if can_resolve_when_down=1. |
||
838 | * This function must not have any side effects. |
||
839 | * |
||
840 | * @param o state pointer, as in {@link NCDModule_func_new2} |
||
841 | * @param name name of the variable to resolve as an {@link NCDStringIndex} identifier |
||
842 | * @param mem value memory to use |
||
843 | * @param out on success, the backend should initialize the value here |
||
844 | * @return 1 if exists, 0 if not exists. If exists, but out of memory, return 1 |
||
845 | * and an invalid value. |
||
846 | */ |
||
847 | typedef int (*NCDModule_func_getvar2) (void *o, NCD_string_id_t name, NCDValMem *mem, NCDValRef *out); |
||
848 | |||
849 | /** |
||
850 | * Function called to resolve an object within a backend instance. |
||
851 | * The backend instance is in up state, or in up or down state if can_resolve_when_down=1. |
||
852 | * This function must not have any side effects. |
||
853 | * |
||
854 | * @param o state pointer, as in {@link NCDModule_func_new2} |
||
855 | * @param name name of the object to resolve as an {@link NCDStringIndex} identifier |
||
856 | * @param out_object the object will be returned here |
||
857 | * @return 1 on success, 0 on failure |
||
858 | */ |
||
859 | typedef int (*NCDModule_func_getobj) (void *o, NCD_string_id_t name, NCDObject *out_object); |
||
860 | |||
861 | /** |
||
862 | * Handler called when the module instance is in a clean state. |
||
863 | * This means that all statements preceding it in the process are |
||
864 | * up, this statement is down, and all following statements are |
||
865 | * uninitialized. When a backend instance goes down, it is guaranteed, |
||
866 | * as long as it stays down, that either this will be called or |
||
867 | * termination will be requested with {@link NCDModule_func_die}. |
||
868 | * The backend instance was in down state. |
||
869 | * |
||
870 | * @param o state pointer, as in {@link NCDModule_func_new2} |
||
871 | */ |
||
872 | typedef void (*NCDModule_func_clean) (void *o); |
||
873 | |||
874 | #define NCDMODULE_FLAG_CAN_RESOLVE_WHEN_DOWN (1 << 0) |
||
875 | |||
876 | /** |
||
877 | * Structure encapsulating the implementation of a module backend. |
||
878 | */ |
||
879 | struct NCDModule { |
||
880 | /** |
||
881 | * If this implements a plain statement, the name of the statement. |
||
882 | * If this implements a method, then "base_type::method_name". |
||
883 | */ |
||
884 | const char *type; |
||
885 | |||
886 | /** |
||
887 | * The base type for methods operating on instances of this backend. |
||
888 | * Any module with type of form "base_type::method_name" is considered |
||
889 | * a method of instances of this backend. |
||
890 | * If this is NULL, the base type will default to type. |
||
891 | */ |
||
892 | const char *base_type; |
||
893 | |||
894 | /** |
||
895 | * Function called to create an new backend instance. |
||
896 | */ |
||
897 | NCDModule_func_new2 func_new2; |
||
898 | |||
899 | /** |
||
900 | * Function called to request termination of a backend instance. |
||
901 | * May be NULL, in which case the default is to call NCDModuleInst_Backend_Dead(). |
||
902 | */ |
||
903 | NCDModule_func_die func_die; |
||
904 | |||
905 | /** |
||
906 | * Function called to resolve a variable within the backend instance. |
||
907 | * May be NULL. |
||
908 | */ |
||
909 | NCDModule_func_getvar func_getvar; |
||
910 | |||
911 | /** |
||
912 | * Function called to resolve a variable within the backend instance. |
||
913 | * May be NULL. |
||
914 | */ |
||
915 | NCDModule_func_getvar2 func_getvar2; |
||
916 | |||
917 | /** |
||
918 | * Function called to resolve an object within the backend instance. |
||
919 | * May be NULL. |
||
920 | */ |
||
921 | NCDModule_func_getobj func_getobj; |
||
922 | |||
923 | /** |
||
924 | * Function called when the backend instance is in a clean state. |
||
925 | * May be NULL. |
||
926 | */ |
||
927 | NCDModule_func_clean func_clean; |
||
928 | |||
929 | /** |
||
930 | * Various flags. |
||
931 | * |
||
932 | * - NCDMODULE_FLAG_CAN_RESOLVE_WHEN_DOWN |
||
933 | * Whether the interpreter is allowed to call func_getvar and func_getobj |
||
934 | * even when the backend instance is in down state (as opposed to just |
||
935 | * in up state. |
||
936 | */ |
||
937 | int flags; |
||
938 | |||
939 | /** |
||
940 | * The amount of memory to preallocate for each module instance. |
||
941 | * Preallocation can be used to avoid having to allocate memory from |
||
942 | * module initialization. The memory can be accessed via the first |
||
943 | * argument to {@link NCDModule_func_new2} and other calls. |
||
944 | */ |
||
945 | int alloc_size; |
||
946 | }; |
||
947 | |||
948 | /** |
||
949 | * Structure encapsulating a group of module backend implementations, |
||
950 | * with global init and free functions. |
||
951 | */ |
||
952 | struct NCDModuleGroup { |
||
953 | /** |
||
954 | * Function called before any instance of any module backend in this |
||
955 | * group is crated. May be NULL. |
||
956 | */ |
||
957 | NCDModule_func_globalinit func_globalinit; |
||
958 | |||
959 | /** |
||
960 | * Function called to clean up after {@link NCDModule_func_globalinit}. |
||
961 | * May be NULL. |
||
962 | */ |
||
963 | NCDModule_func_globalfree func_globalfree; |
||
964 | |||
965 | /** |
||
966 | * Array of module backends. The array must be terminated with a |
||
967 | * structure that has a NULL type member. |
||
968 | */ |
||
969 | const struct NCDModule *modules; |
||
970 | |||
971 | /** |
||
972 | * A pointer to an array of strings which will be mapped to |
||
973 | * {@link NCDStringIndex} string identifiers for the module to use. |
||
974 | * The array must be terminated by NULL. The resulting string |
||
975 | * identifiers will be available in the 'strings' member in |
||
976 | * {@link NCDInterpModuleGroup}. |
||
977 | */ |
||
978 | const char *const*strings; |
||
979 | |||
980 | /** |
||
981 | * A pointer to an array of global functions implemented by this module |
||
982 | * group. The array must be terminated with a structure that has a NULL |
||
983 | * func_name member. May be NULL. |
||
984 | */ |
||
985 | struct NCDModuleFunction const *functions; |
||
986 | }; |
||
987 | |||
988 | /** |
||
989 | * Represents an {@link NCDModule} within an interpreter. |
||
990 | * This structure is initialized by the interpreter when it loads a module group. |
||
991 | */ |
||
992 | struct NCDInterpModule { |
||
993 | /** |
||
994 | * A copy of the original NCDModule structure, |
||
995 | */ |
||
996 | struct NCDModule module; |
||
997 | |||
998 | /** |
||
999 | * The string identifier of this module's base_type (or type if base_type is |
||
1000 | * not specified) according to {@link NCDStringIndex}. |
||
1001 | */ |
||
1002 | NCD_string_id_t base_type_id; |
||
1003 | |||
1004 | /** |
||
1005 | * A pointer to the {@link NCDInterpModuleGroup} representing the group |
||
1006 | * this module belongs to. |
||
1007 | */ |
||
1008 | struct NCDInterpModuleGroup *group; |
||
1009 | }; |
||
1010 | |||
1011 | /** |
||
1012 | * Represents an {@link NCDModuleGroup} within an interpreter. |
||
1013 | * This structure is initialized by the interpreter when it loads a module group. |
||
1014 | */ |
||
1015 | struct NCDInterpModuleGroup { |
||
1016 | /** |
||
1017 | * A copy of the original NCDModuleGroup structure. |
||
1018 | */ |
||
1019 | struct NCDModuleGroup group; |
||
1020 | |||
1021 | /** |
||
1022 | * An array of string identifiers corresponding to the strings |
||
1023 | * in the 'strings' member of NCDModuleGroup. May be NULL if there |
||
1024 | * are no strings in the NCDModuleGroup. |
||
1025 | */ |
||
1026 | NCD_string_id_t *strings; |
||
1027 | |||
1028 | /** |
||
1029 | * Pointer which allows the module to keep private interpreter-wide state. |
||
1030 | * This can be freely modified by the module; the interpeter will not |
||
1031 | * read or write it. |
||
1032 | */ |
||
1033 | void *group_state; |
||
1034 | }; |
||
1035 | |||
1036 | /** |
||
1037 | * An abstraction of function call evaluations, mutually decoupling the |
||
1038 | * interpreter and the function implementations. |
||
1039 | * |
||
1040 | * The function implementation is given an instance of this structure |
||
1041 | * in the evaluation callback (func_eval), and uses it to request |
||
1042 | * information and submit results. The function implementation does these |
||
1043 | * things by calling the various NCDCall functions with the NCDCall |
||
1044 | * instance. Note that function arguments are evaluated on demand from |
||
1045 | * the function implementation. This enables behavior such as |
||
1046 | * short-circuit evaluation of logical operators. |
||
1047 | * |
||
1048 | * The NCDCall struct has a value semantic - it can be copied |
||
1049 | * around freely by the function implementation during the |
||
1050 | * lifetime of the evaluation call. |
||
1051 | */ |
||
1052 | typedef struct { |
||
1053 | struct NCDCall_interp_shared const *interp_shared; |
||
1054 | void *interp_user; |
||
1055 | struct NCDInterpFunction const *interp_function; |
||
1056 | size_t arg_count; |
||
1057 | NCDValMem *res_mem; |
||
1058 | NCDValRef *out_ref; |
||
1059 | } NCDCall; |
||
1060 | |||
1061 | /** |
||
1062 | * Used by the intepreter to call a function. |
||
1063 | * |
||
1064 | * It calls the func_eval callback of the function implementation |
||
1065 | * with an appropriately initialized NCDCall value. This is the only |
||
1066 | * NCDCall related function used by the interpreter. |
||
1067 | * |
||
1068 | * As part of the call, callbacks to the interpreter (given in interp_shared) |
||
1069 | * may occur. All of these callbacks are passed interp_user as the first |
||
1070 | * argument. The callbacks are: |
||
1071 | * - logfunc (to log a message), |
||
1072 | * - func_eval_arg (to evaluate a particular function argument). |
||
1073 | * |
||
1074 | * @param interp_shared pointer to things expected to be the same for all |
||
1075 | * function calls by the interpreter. This includes interpreter callbacks. |
||
1076 | * @param interp_user pointer to be passed through to interpreter callbacks |
||
1077 | * @param interp_function the function to call. The evaluation function of |
||
1078 | * the function implementation that will be called is taken from here |
||
1079 | * (interp_function->function.func_eval), but this is also exposed to the |
||
1080 | * function implementation, so it should be initialized appropriately. |
||
1081 | * @param arg_count number of arguments passed to the function. |
||
1082 | * The function implementation is only permitted to attempt evaluation |
||
1083 | * of arguments with indices lesser than arg_count. |
||
1084 | * @param res_mem the (initialized) value memory object for the result to |
||
1085 | * be stored into. However this may also be used as storage for temporary |
||
1086 | * values computed as part of the call. |
||
1087 | * @param res_out on success, *res_out will be set to the result of the call |
||
1088 | * @return 1 on success, 0 on error |
||
1089 | */ |
||
1090 | int NCDCall_DoIt ( |
||
1091 | struct NCDCall_interp_shared const *interp_shared, void *interp_user, |
||
1092 | struct NCDInterpFunction const *interp_function, |
||
1093 | size_t arg_count, NCDValMem *res_mem, NCDValRef *res_out |
||
1094 | ) WARN_UNUSED; |
||
1095 | |||
1096 | /** |
||
1097 | * Returns a pointer to the NCDInterpFunction object for the function, |
||
1098 | * initialized by the interpreter. This alows, among other things, |
||
1099 | * determining which function is being called, and getting the module |
||
1100 | * group's private data pointer. |
||
1101 | */ |
||
1102 | struct NCDInterpFunction const * NCDCall_InterpFunction (NCDCall const *o); |
||
1103 | |||
1104 | /** |
||
1105 | * Returns a pointer to an NCDModuleInst_iparams structure, exposing |
||
1106 | * services provided by the interpreter. |
||
1107 | */ |
||
1108 | struct NCDModuleInst_iparams const * NCDCall_Iparams (NCDCall const *o); |
||
1109 | |||
1110 | /** |
||
1111 | * Returns the number of arguments for the function call. |
||
1112 | */ |
||
1113 | size_t NCDCall_ArgCount (NCDCall const *o); |
||
1114 | |||
1115 | /** |
||
1116 | * Attempts to evaluate a function argument. |
||
1117 | * |
||
1118 | * @param index the index of the argument to be evaluated. Must be |
||
1119 | * in the range [0, ArgCount). |
||
1120 | * @param mem the value memory object for the value to be stored into. |
||
1121 | * However temporary value data may also be stored here. |
||
1122 | * @return on success, the value reference to the argument value; |
||
1123 | * on failure, an invalid value reference |
||
1124 | */ |
||
1125 | NCDValRef NCDCall_EvalArg (NCDCall const *o, size_t index, NCDValMem *mem); |
||
1126 | |||
1127 | /** |
||
1128 | * Returns a pointer to the value memory object that the result |
||
1129 | * of the call should be stored into. The memory object may also |
||
1130 | * be used to store temporary value data. |
||
1131 | */ |
||
1132 | NCDValMem * NCDCall_ResMem (NCDCall const *o); |
||
1133 | |||
1134 | /** |
||
1135 | * Provides result value of the evaluation to the interpreter. |
||
1136 | * Note that this only stores the result without any immediate |
||
1137 | * action. |
||
1138 | * |
||
1139 | * Passing an invalid value reference indicates failure of the |
||
1140 | * call, though failure is also assumed if this function is |
||
1141 | * not called at all during the call. When a non-invalid |
||
1142 | * value reference is passed (indicating success), it must point |
||
1143 | * to a value stored within the memory object returned by |
||
1144 | * NCDCall_ResMem. |
||
1145 | * |
||
1146 | * @param ref the result value for the call, or an invalid |
||
1147 | * value reference to indicate failure of the call |
||
1148 | */ |
||
1149 | void NCDCall_SetResult (NCDCall const *o, NCDValRef ref); |
||
1150 | |||
1151 | /** |
||
1152 | * Returns a log context that can be used to log messages |
||
1153 | * associated with the call. |
||
1154 | */ |
||
1155 | BLogContext NCDCall_LogContext (NCDCall const *o); |
||
1156 | |||
1157 | /** |
||
1158 | * A structure initialized by the interpreter and passed |
||
1159 | * to NCDCall_DoIt for function evaluations. |
||
1160 | * It contains a pointer to things expected to be the same for all |
||
1161 | * function calls by the interpreter, so it can be initialized once |
||
1162 | * and not for every call. |
||
1163 | */ |
||
1164 | struct NCDCall_interp_shared { |
||
1165 | /** |
||
1166 | * A callack for log messages originating from the function call. |
||
1167 | * The first argument is the interp_user argument to NCDCall_DoIt. |
||
1168 | */ |
||
1169 | BLog_logfunc logfunc; |
||
1170 | |||
1171 | /** |
||
1172 | * A callback for evaluating function arguments. |
||
1173 | * |
||
1174 | * @param user interpreter private data (the interp_user argument |
||
1175 | * to NCDCall_DoIt) |
||
1176 | * @param index the index of the argument to be evaluated. |
||
1177 | * This will be in the range [0, arg_count). |
||
1178 | * @param mem the value memory object where the result of the |
||
1179 | * evaluation should be stored. Temporary value data may also |
||
1180 | * be stored here. |
||
1181 | * @param out on success, *out should be set to the value reference |
||
1182 | * to the result of the evaluation. An invalid value reference is |
||
1183 | * permitted, in which case failure is assumed. |
||
1184 | * @return 1 on success (but see above), 0 on failure |
||
1185 | */ |
||
1186 | int (*func_eval_arg) (void *user, size_t index, NCDValMem *mem, NCDValRef *out); |
||
1187 | |||
1188 | /** |
||
1189 | * A pointer to an NCDModuleInst_iparams structure, exposing |
||
1190 | * services provided by the interpreter. |
||
1191 | */ |
||
1192 | struct NCDModuleInst_iparams const *iparams; |
||
1193 | }; |
||
1194 | |||
1195 | /** |
||
1196 | * This structure is initialized statically by a function |
||
1197 | * implementation to describe the function and provide |
||
1198 | * the resources required for its evaluation by the interpreter. |
||
1199 | * |
||
1200 | * These structures always appear in arrays, pointed to by |
||
1201 | * the functions pointer in the NCDModuleGroup structure. |
||
1202 | */ |
||
1203 | struct NCDModuleFunction { |
||
1204 | /** |
||
1205 | * The name of the function. |
||
1206 | * NULL to terminate the array of functions. |
||
1207 | */ |
||
1208 | char const *func_name; |
||
1209 | |||
1210 | /** |
||
1211 | * Callback for evaluating the function. |
||
1212 | */ |
||
1213 | void (*func_eval) (NCDCall call); |
||
1214 | }; |
||
1215 | |||
1216 | /** |
||
1217 | * Represents an {@link NCDModuleFunction} within an interpreter. |
||
1218 | * This structure is initialized by the interpreter when it loads a module group. |
||
1219 | */ |
||
1220 | struct NCDInterpFunction { |
||
1221 | /** |
||
1222 | * A copy of the original NCDModuleFunction structure. |
||
1223 | * We could just use a pointer to the original statically defined structure, |
||
1224 | * but then we wouldn't be annoying the premature-optimization hipsters. |
||
1225 | */ |
||
1226 | struct NCDModuleFunction function; |
||
1227 | |||
1228 | /** |
||
1229 | * The string identifier of this functions's name. according to |
||
1230 | * {@link NCDStringIndex}. |
||
1231 | */ |
||
1232 | NCD_string_id_t func_name_id; |
||
1233 | |||
1234 | /** |
||
1235 | * A pointer to the {@link NCDInterpModuleGroup} representing the group |
||
1236 | * this function belongs to. |
||
1237 | */ |
||
1238 | struct NCDInterpModuleGroup *group; |
||
1239 | }; |
||
1240 | |||
1241 | #endif |