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:
parent
26af700336
commit
bae2136827
1 changed files with 72 additions and 0 deletions
72
documentation/Hooks.md
Normal file
72
documentation/Hooks.md
Normal 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);
|
||||
}
|
||||
```
|
Loading…
Add table
Reference in a new issue