BadVPN – Blame information for rev 1

Subversion Repositories:
Rev:
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