VILLASnode/doc/Hooks.md

# 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`):

```
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.

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. |

## 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:

	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);
	}