Collaboration diagram for Event Vectors:

Data Structures
struct	em_event_vector_info_t
	Vector event information filled by em_event_vector_info() More...

Functions
void	em_event_vector_free (em_event_t vector_event)
	Free the vector event only, not the events it contains.

uint32_t	em_event_vector_tbl (em_event_t vector_event, em_event_t **event_tbl)
	Get the event vector table from an event of (major) type EM_EVENT_TYPE_VECTOR.

em_event_type_t	em_event_vector_type (em_event_t event_vector)

em_status_t	em_event_vector_type_set (em_event_t event_vector, em_event_type_t type)

uint32_t	em_event_vector_size (em_event_t vector_event)
	Number of event handles available (set) in a vector.

void	em_event_vector_size_set (em_event_t vector_event, uint32_t size)
	Set the number of event handles stored in a vector.

uint32_t	em_event_vector_max_size (em_event_t vector_event)
	Maximum number of event handles that can be stored in a vector.

em_status_t	em_event_vector_info (em_event_t vector_event, em_event_vector_info_t *vector_info)
	Retrieve information about the given vector event.

Detailed Description

Vector Events

Event (major) Type: EM_EVENT_TYPE_VECTOR

Vector events contain a table of events ('em_event_t event_tbl[]'). EM supports two "modes" of event vectors selectable via the EM config file option 'vector.backend': 1) vector.backend = "event" Event vectors can contain events of any type. Aggregator queues bundle multiple events into a single event vector for more efficient queuing and scheduling. This mode requires newer ODP versions with support for ODP event vectors and event/queue aggregation. 2) vector.backend = "packet" (legacy mode) Event vectors contain only events of major type EM_EVENT_TYPE_PACKET. Storing events of another type into the event-table is an error and leads to undefined behaviour. This mode works on older ODP versions that don't support ODP event vectors. Event/queue aggregation is NOT supported. The vector backend mode is either-or and cannot be mixed in the same EM instance.

Event vector pools are created with em_pool_create() with the pool event-type set to EM_EVENT_TYPE_VECTOR. Event vectors can then be allocated from vector pools by calling em_alloc(..., vector_pool). To free the vector event along with all events it contains, use em_free() or em_free_multi(). To free the vector event only, not the events it contains, use em_event_vector_free().

A newly allocated vector event has an empty event-table (size = 0). The application must fill the event-table via em_event_vector_tbl() and then set the vector size with em_event_vector_size_set() before sending or otherwise using the vector.

The following general event APIs are NOT supported for vector events:

em_event_pointer() / em_event_pointer_and_size() - use em_event_vector_tbl() instead
em_event_size() - use em_event_vector_size() instead
em_event_clone() / em_event_clone_part()
em_event_ref()

Vector events support user areas if the vector pool was configured with a non-zero user area size (see em_pool_create()).

Function Documentation

◆ em_event_vector_free()

void em_event_vector_free ( em_event_t vector_event )

Free the vector event only, not the events it contains.

Frees only the vector event itself and not the events it contains in its vector-table. To free the vector event along with all events it contains, use em_free() or em_free_multi().

Note: Passing EM_EVENT_UNDEF or a non-vector event triggers an error. Only events of major type EM_EVENT_TYPE_VECTOR are accepted.

Parameters

vector_event Vector event handle

Examples: bench_event.c.

Definition at line 1856 of file event_machine_event.c.

◆ em_event_vector_info()

em_status_t em_event_vector_info	(	em_event_t	vector_event,
		em_event_vector_info_t *	vector_info
	)

Retrieve information about the given vector event.

Vector event information is output via the struct 'vector_info'. Combines em_event_vector_tbl(), em_event_vector_size() and em_event_vector_max_size() into one function call.

Parameters

	vector_event	Vector event handle to get the information of.
[out]	vector_info	Output struct into which the vector information is stored.

Returns: EM status code indicating success or failure of the operation.

Return values

EM_OK	Operation successful.
Other	Operation FAILED and no valid vector info could be obtained, 'vector_info' is all NULL/zero(0) in this case.

Examples: bench_event.c.

Definition at line 2155 of file event_machine_event.c.

◆ em_event_vector_max_size()

uint32_t em_event_vector_max_size ( em_event_t vector_event )

Maximum number of event handles that can be stored in a vector.

Returns the maximum number of events that can be stored into the event-table of the given vector event, i.e. the max-size that can be used with em_event_vector_size_set(). The max-size might be larger than the size requested during allocation and instead reflects the vector-size used when creating the EM event vector pool.

Parameters

vector_event Vector event handle

Returns: The maximum number of event handles that can be stored in the vector

Return values

>0	on success
0	on failure or if EM cannot retrieve the max size (non-EM pool).

Examples: bench_event.c.

Definition at line 2133 of file event_machine_event.c.

◆ em_event_vector_size()

uint32_t em_event_vector_size ( em_event_t vector_event )

Number of event handles available (set) in a vector.

Returns the number of available events in the vector. Note that the returned 'size' indicates how many valid events are stored in the vector's event-table. The 'size' neither indicates the alloc-size (size given to em_alloc()) nor the max-size of the event-table, use em_event_vector_max_size() or em_event_vector_info() to obtain that information.

The types of events that can be stored in the event-table depend on the selected vector backend mode (see EM config file option 'vector.backend'):

vector.backend = "event": events of any type can be stored
vector.backend = "packet": only events of major type EM_EVENT_TYPE_PACKET

Parameters

vector_event Vector event handle

Returns: The number of event handles available (set) in the vector

Note: A newly allocated vector has an empty event-table and thus the returned size is zero until updated with em_event_vector_size_set()

Examples: bench_event.c.

Definition at line 2063 of file event_machine_event.c.

◆ em_event_vector_size_set()

void em_event_vector_size_set	(	em_event_t	vector_event,
		uint32_t	size
	)

Set the number of event handles stored in a vector.

Update the number of event handles stored in a vector. This function shall be used to set the number of events available in the given vector when the application itself is producing (or updating) the event vector. Only valid event handles can be stored into the vector's event-table. The events must be stored into the vector before setting the size, i.e. first add/remove events to/from the vector's event-table (within max-size limits) and only then set the size.

The types of events that can be stored in the event-table depend on the selected vector backend mode (see EM config file option 'vector.backend'):

vector.backend = "event": events of any type can be stored
vector.backend = "packet": only events of major type EM_EVENT_TYPE_PACKET

Parameters

vector_event	Vector event handle
size	Number of event handles in the vector

Note: The maximum number of event handles the vector can hold is defined by em_pool_cfg_t::subpool[i].size or can be obtained for a specific vector with em_event_vector_max_size().; All handles in the vector table (0 ... size - 1) must be valid EM event handles (EM_EVENT_UNDEF not allowed).; Setting 'size' larger than the vector's max_size (see em_event_vector_max_size()) results in undefined behavior. EM may report this as an error depending on the check level.

Examples: bench_event.c, and loop_united.c.

Definition at line 2091 of file event_machine_event.c.

◆ em_event_vector_tbl()

uint32_t em_event_vector_tbl	(	em_event_t	vector_event,
		em_event_t **	event_tbl
	)

Get the event vector table from an event of (major) type EM_EVENT_TYPE_VECTOR.

The event vector table is an array of event handles (em_event_t) stored in a contiguous memory location for events with major event type set to EM_EVENT_TYPE_VECTOR. Upon completion of this function, the event table pointer of the given vector event is returned via the output argument 'event_tbl'.

The types of events that can be stored in the event-table depend on the selected vector backend mode (see EM config file option 'vector.backend'):

vector.backend = "event": events of any type can be stored
vector.backend = "packet": only events of major type EM_EVENT_TYPE_PACKET Invalid event handles (EM_EVENT_UNDEF) shall not be stored in the event-table.

Parameters

	vector_event	Vector event handle
[out]	event_tbl	Pointer into which the event table (ptr) is written

Returns: Number of event handles currently stored (set) in the vector, i.e. the current size. The event-table pointer can be used to access/write entries up to max_size (see em_event_vector_max_size()), but only entries at indices [0 ... return_value - 1] contain valid events.

Return values

0	on error and *event_tbl is set to NULL

Note: A newly allocated vector has an empty event-table and thus the returned size is zero until updated with em_event_vector_size_set().

em_event_type_t event_type = em_event_type(vector_event);
 
if (em_event_type_major(event_type) == EM_EVENT_TYPE_VECTOR) {
   em_event_t *event_tbl = NULL;
   uint32_t num = em_event_vector_tbl(vector_event, &event_tbl);
 
   if (!num)
           return;
 
   for (uint32_t i = 0; i < num; i++) {
           event = event_tbl[i];
           ... process 'event' ...
   }
}

See also: em_event_vector_size_set()

Examples: bench_event.c, and loop_united.c.

Definition at line 1895 of file event_machine_event.c.

◆ em_event_vector_type()

em_event_type_t em_event_vector_type ( em_event_t event_vector )

Return the event type of events stored in the event vector table.

The vector event itself has major type EM_EVENT_TYPE_VECTOR, but the events stored in its event table have their own major type. This function returns that event table type. The special type EM_EVENT_TYPE_ANY indicates that the vector contains multiple event types or that the type is unknown.

After allocation (em_alloc() etc.), before any events are added, the event table type depends on the selected vector backend mode as follows (see the EM config file option 'vector.backend'): 1) vector.backend = "event": type is initialized to EM_EVENT_TYPE_ANY 2) vector.backend = "packet": type is initialized to EM_EVENT_TYPE_PACKET Event aggregators set the table type to the event type common to all events or to EM_EVENT_TYPE_ANY if the events are mixed or the type cannot be determined. The table type can also be set with em_event_vector_type_set().

Parameters

event_vector Event handle of the event vector

Returns: Event type

Return values

EM_EVENT_TYPE_UNDEF on error

Definition at line 1982 of file event_machine_event.c.

◆ em_event_vector_type_set()

em_status_t em_event_vector_type_set	(	em_event_t	event_vector,
		em_event_type_t	type
	)

Set the type of the events stored in the event vector table.

The specified type is stored in vector metadata and can be queried later with em_event_vector_type(). The type must match the vector contents when the vector is passed to an EM API.

The set type must apply to all events stored in the vector's event-table, otherwise the result is undefined when the vector is passed to an EM API.

The table type that can be set depends on the selected vector backend mode as follows (see the EM config file option 'vector.backend'): 1) vector.backend = "event": all event types are supported and can be set. Use EM_EVENT_TYPE_ANY if the vector contains multiple event types or if the type is unknown, otherwise use the common event type of all entries. 2) vector.backend = "packet": only types with the major part set to EM_EVENT_TYPE_PACKET are accepted.

This call is not needed if the current table type already matches the updated contents.

Parameters

event_vector	Event handle of the event vector
type	Event type

Returns: EM_OK on success

Return values

Other on failure (e.g. invalid event, invalid type or type not compatible with the vector backend mode)

Definition at line 1994 of file event_machine_event.c.

Data Structures

Functions

Detailed Description

Vector Events

Function Documentation

◆ em_event_vector_free()

◆ em_event_vector_info()

◆ em_event_vector_max_size()

◆ em_event_vector_size()

◆ em_event_vector_size_set()

◆ em_event_vector_tbl()

◆ em_event_vector_type()

◆ em_event_vector_type_set()