diff --git a/Doxyfile b/Doxyfile index 3c4c2f2f0..f7f1a2be1 100644 --- a/Doxyfile +++ b/Doxyfile @@ -838,7 +838,7 @@ EXCLUDE_SYMBOLS = # that contain example code fragments that are included (see the \include # command). -EXAMPLE_PATH = server/etc/ +EXAMPLE_PATH = etc/ # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and diff --git a/doc/Hooks.md b/doc/Hooks.md index 4e9782bd3..6ec3b9828 100644 --- a/doc/Hooks.md +++ b/doc/Hooks.md @@ -21,39 +21,39 @@ Example applications for hooks might be: Each path is allowed to have multiple active hooks. Those can be configured in the path section using the `hooks` setting: -``` -paths = [ - { - in = "input_node", - out = "output_node", - hooks = [ "fir", "print" ] -# hooks = "decimate" // alternative syntax for a single hook - } -] -``` + paths = [ + { + in = "input_node", + out = "output_node", + hooks = [ "fir", "print" ] + # hooks = "decimate" // alternative syntax for a single hook + } + ] **Please note:** the hooks will be executed in the order they are given in the configuration file! ## API -The interface for user-defined hook functions is defined in (server/include/hooks.h): +The interface for user-defined hook functions is defined in (`server/include/hooks.h`): -```c -typedef int (*hook_cb_t)(struct path *p); +``` +typedef int (*hook_cb_t)(struct path *p, struct hook *h, int when); ``` There are several occasions when a hook can be executed in the program flow (@see hook_type). -There is a dedicated queue for each occasion: +There is a dedicated queue for each occasion. -| Queue | Desciption | -| ------------------- | -------------------------------------------------------------- | -| `HOOK_PATH_START` | Called whenever a path is started; before threads are created. | -| `HOOK_PATH_STOP` | Called whenever a path is stopped; after threads are destoyed. | +The queue for which a hook can be called is encoded as a mask and specified during registration of that hook. + +| Queue | Desciption | +| --------------------- | --------------------------------------------------------------------- | +| `HOOK_PATH_START` | Called whenever a path is started; before threads are created. | +| `HOOK_PATH_STOP` | Called whenever a path is stopped; after threads are destoyed. | | `HOOK_PATH_RESTART` | Called whenever a new simulation case is started. This is detected by a sequence no equal to zero. | -| `HOOK_PRE` | Called when a new packet of messages (samples) was received. | -| `HOOK_POST` | Called after each message (sample) of a packet was processed. | -| `HOOK_MSG` | Called for each message (sample) in a packet. | -| `HOOK_PERIODIC` | Called periodically. Period is set by global 'stats' option in the configuration file. | +| `HOOK_PRE` | Called when a new packet of messages (samples) was received. | +| `HOOK_POST` | Called after each message (sample) of a packet was processed. | +| `HOOK_MSG` | Called for each message (sample) in a packet. | +| `HOOK_PERIODIC` | Called periodically. Period is set by global 'stats' option in the configuration file. | ## Examples @@ -62,11 +62,9 @@ Use one of those as a starting point for your own hook. A typical hook function might look like this one: -```c -int my_super_hook_function(struct path *p) -{ - struct msg *last_received_msg = p->current; - - printf("The last message contained %u values\n", last_received_msg->length); -} -``` + int my_super_hook_function(struct path *p, struct hook *h, int when) + { + struct msg *last_received_msg = p->current; + + printf("The last message contained %u values\n", last_received_msg->length); + } diff --git a/include/list.h b/include/list.h index 6f44ee01d..725f670d8 100644 --- a/include/list.h +++ b/include/list.h @@ -1,6 +1,10 @@ -/** A generic linked list +/** A generic list implementation. * - * Linked lists a used for several data structures in the code. + * This is a generic implementation of a list which can store void pointers to + * arbitrary data. The data itself is not stored or managed by the list. + * + * Internally, an array of pointers is used to store the pointers. + * If needed, this array will grow by realloc(). * * @file * @author Steffen Vogel @@ -42,6 +46,7 @@ typedef void (*dtor_cb_t)(void *); /** Callback to search or sort a list. */ typedef int (*cmp_cb_t)(const void *, const void *); +/* The list data structure. */ struct list { void **array; /**< Array of pointers to list elements */ size_t capacity; /**< Size of list::array in elements */ @@ -50,7 +55,11 @@ struct list { pthread_mutex_t lock; /**< A mutex to allow thread-safe accesses */ }; -/** Initialize a list */ +/** Initialize a list. + * + * @param l A pointer to the list data structure. + * @param dtor A function pointer to a desctructor which will be called for every list item when the list is destroyed. + */ void list_init(struct list *l, dtor_cb_t dtor); /** Destroy a list and call destructors for all list elements */ @@ -62,9 +71,9 @@ void list_push(struct list *l, void *p); /** Remove all occurences of a list item */ void list_remove(struct list *l, void *p); -/** Search the list for an element whose first element is a character array which matches name. +/** Return the first list element which is identified by a string in its first member variable. * - * List elements should be of the following form: + * List elements are pointers to structures of the following form: * * struct obj { * char *name; diff --git a/include/msg.h b/include/msg.h index a3fa9af4f..c35e2a108 100644 --- a/include/msg.h +++ b/include/msg.h @@ -51,7 +51,8 @@ int msg_verify(struct msg *m); /** Print a raw message in human readable form to a file stream. * - * @param f The file handle from fopen() or stdout, stderr. + * @param buf A character buffer of len bytes. + * @param len The size of buf. * @param m A pointer to the message. * @param flags See msg_flags. * @param offset A optional offset in seconds. Only used if flags contains MSG_PRINT_OFFSET. @@ -61,7 +62,7 @@ int msg_print(char *buf, size_t len, struct msg *m, int flags, double offset); /** Read a message from a character buffer. * - * @param f The file handle from fopen() or stdin. + * @param line A string which should be parsed. * @param m A pointer to the message. * @param flags et MSG_PRINT_* flags for each component found in sample if not NULL. See msg_flags. * @param offset Write offset to this pointer if not NULL. @@ -73,12 +74,18 @@ int msg_scan(const char *line, struct msg *m, int *fl, double *off); /** Print a raw message in human readable form to a file stream. * * @see msg_print() + * @param f The file handle from fopen() or stdout, stderr. + * @retval 0 Success. Everything went well. + * @retval <0 Error. Something went wrong. */ int msg_fprint(FILE *f, struct msg *m, int flags, double offset); /** Read a message from a file stream. * * @see msg_scan() + * @param f The file handle from fopen() or stdin. + * @retval 0 Success. Everything went well. + * @retval <0 Error. Something went wrong. */ int msg_fscan(FILE *f, struct msg *m, int *flags, double *offset);