ovni/doc/dev/channels.md

Channels

As the emulation progresses, information is written in the PRV trace to record the new states. The emulator has specific mechanism to handle the output of new states in the PRV trace via channels. A channel stores a value that represents an state at a given point in time and typically corresponds to the value that will be observed in the Paraver timeline.

!!! Note

The emulator receives input *events* and performs *state*
transitions which are written into the Paraver trace.

Channels become dirty when a new value is written to them. No other modifications are allowed by default until the channel is flushed by calling chan_flush(). This behavior can be controlled with the CHAN_DIRTY_WRITE property. By default, a duplicated value cannot be written into a channel, unless the CHAN_ALLOW_DUP or CHAN_IGNORE_DUP properties are set.

A channel has an unique name used to identify the channel when debugging and also to create derived channels. The name can be set following the printf style when calling chan_init().

Types

There are two types of channels, single and stack. The type single only stores one value which is updated by chan_set(). The stack type allows the channel to record multiple values in a stack by using chan_push() and chan_pop(). The value of the channels is the topmost in the stack (the last pushed).

Notice that the chan_pop() function uses the same value being pop()'ed as argument. The function checks that the stack contains the expected value, forcing the emulator to always receive a matching pair of push and pop values.

After the channel initialization, the value of the channels is null. A channel with an empty stack also returns the value null when being read.

Data value

The data type of a channel is handled by the value structure. This structure can store a null value, a 64 bit integer or a double. Any data type can be written to a channel and multiple data types can be stored in the stack.

!!! Note

For now only null and int64 types are allowed when the channel is connected
to a Paraver trace.

Properties

Channels have properties that can be set by chan_prop_set(). Setting the CHAN_DIRTY_WRITE property to true allows a channel to modify its value while being in the dirty state.

Duplicate values

By default, writing the same value to a channel twice is forbidden and will result in a error. The property CHAN_ALLOW_DUP allows writing the same value to the channel. However, the property CHAN_IGNORE_DUP will ignore the attempt to write the duplicated value with no error.

Callback

A unique function can be set to each channel which will be called once a channel becomes dirty with chan_set_dirty_cb(). This callback will be called before chan_set(), chan_push() or chan_pop() returns. The patch bay uses this callback to detect when a channel is modified an run other callbacks.