1
0
Fork 0
mirror of https://git.rwth-aachen.de/acs/public/villas/node/ synced 2025-03-09 00:00:00 +01:00

Create Hooks.md

This commit is contained in:
Steffen Vogel 2015-08-10 13:54:10 +02:00
parent 26af700336
commit bae2136827

72
documentation/Hooks.md Normal file
View file

@ -0,0 +1,72 @@
# Hooks
Hooks are simple callback functions which are called whenever a message is processed by a path.
There are several built-in hooks for:
- collecting, show & reset statistics
- drop reordered messages
- verify message headers
- handle simulation restarts
But main goal of this mechanism is to provide extensibility for the end user.
Example applications for hooks might be:
1. Filter sample values
2. Manipulate sample values: FIR
3. Transform sample values: FFT, DCT
4. Update network emulation settings based on sample values
## Configuration
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
}
]
```
**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):
```c
typedef int (*hook_cb_t)(struct path *p);
```
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:
| 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. |
## Examples
There are already several hooks defined in (server/src/hooks.c).
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);
}
```