 |
EM-ODP 4.4.0
Event Machine on ODP
|
|
EM-ODP 4.4.0
Event Machine on ODP
|
Functions | |
| em_event_t | em_event_ref (em_event_t event) |
| bool | em_event_has_ref (em_event_t event) |
Normally, each event is associated with one event handle (em_event_t) - each event allocation produces a new event (and associated payload data) that can be processed, sent or freed. When the user EO has allocated or received an event from a queue, the event payload data may be read and written as needed by the application. An exception to the above described scenario happens when using event references. An event reference is an additional event handle referring to an existing event. New references are created with the em_event_ref() API call. The intent of using multiple references is to avoid event copies. An event that has multiple references shares its data with the other reference handles and thus the (shared) data must not be modified. Reading event data from a reference is allowed. Writes to the event data must only be done when there is a single event handle left, i.e. when em_event_has_ref(event) returns 'false'. Results are undefined if these restrictions are not observed. The event is freed when the last reference, including the original event, is freed. It is not allowed to use event references with event groups since assigning an event that has references to an event group would assign all the references to the event group resulting in undefined behaviour. E.g. using em_send_group()/em_send_group_multi() to send a reference is wrong.
| bool em_event_has_ref | ( | em_event_t | event | ) |
Test if an event has references
An event that has multiple references share data with other events and thus the (shared) data must not be modified.
New references are created with the em_event_ref() API call. The intent of multiple references is to avoid event copies. When a reference is created, this function returns 'true' for both events (i.e. for the original event and the new reference).
| event | Event handle |
| false | This event has no references |
| true | The event has multiple references |
Definition at line 1844 of file event_machine_event.c.
| em_event_t em_event_ref | ( | em_event_t | event | ) |
Create a reference to an event
A reference is an additional event handle referring to an existing event. As long as an event has multiple references, none of them (including 'event') should be used to modify the event. Reading event data from a reference is allowed. Writes to the event data must only be done when there is a single event handle left, i.e. when em_event_has_ref(event) returns 'false'. Results are undefined if these restrictions are not observed.
The event is freed when the last reference, including the original event, is freed.
Currently only references to events of (major) type EM_EVENT_TYPE_PACKET can be created. References to vector events (EM_EVENT_TYPE_VECTOR), sw buffer events (EM_EVENT_TYPE_SW) or other event types are not supported.
It is not allowed to use event references with event groups since assigning an event that has references to an event group would assign all the references to the event group resulting in undefined behaviour. E.g. using em_send_group()/em_send_group_multi() to send a reference is wrong.
| event | Event handle for which a reference is to be created. |
| EM_EVENT_UNDEF | on failure |
Definition at line 1791 of file event_machine_event.c.