Collaboration diagram for Events:

Modules
	Event References

	Event User Area

	Event Vectors

Macros
#define	em_event_get_size em_event_size

#define	em_event_get_pool em_event_pool

#define	em_event_get_pool_subpool em_event_pool_subpool

#define	em_event_get_type em_event_type

#define	em_get_type_major em_event_type_major

#define	em_get_type_minor em_event_type_minor

#define	em_event_get_type_multi em_event_type_multi

Typedefs
typedef enum em_event_type_major_e	em_event_type_major_e

typedef enum em_event_type_sw_minor_e	em_event_type_sw_minor_e

Enumerations
enum	em_event_type_major_e { EM_EVENT_TYPE_UNDEF = 0 , EM_EVENT_TYPE_SW = 1 << 24 , EM_EVENT_TYPE_PACKET = 2 << 24 , EM_EVENT_TYPE_TIMER = 3 << 24 , EM_EVENT_TYPE_CRYPTO = 4 << 24 , EM_EVENT_TYPE_VECTOR = 5 << 24 , EM_EVENT_TYPE_TIMER_IND = 6 << 24 , EM_EVENT_TYPE_ODP = 7 << 24 , EM_EVENT_TYPE_ANY = 8 << 24 }

enum	em_event_type_sw_minor_e { EM_EVENT_TYPE_SW_DEFAULT = 0 }

Functions
em_event_t	em_alloc (uint32_t size, em_event_type_t type, em_pool_t pool)

int	em_alloc_multi (em_event_t events[], int num, uint32_t size, em_event_type_t type, em_pool_t pool)

void	em_free (em_event_t event)

void	em_free_multi (em_event_t events[], int num)

em_status_t	em_send (em_event_t event, em_queue_t queue)

int	em_send_multi (const em_event_t events[], int num, em_queue_t queue)

void *	em_event_pointer (em_event_t event)

void *	em_event_pointer_and_size (em_event_t event, uint32_t *size)
	Get a pointer to the event structure/data as well as the event size.

uint32_t	em_event_size (em_event_t event)

em_pool_t	em_event_pool (em_event_t event)
	Returns the EM event-pool the event was allocated from.

em_pool_t	em_event_pool_subpool (em_event_t event, int *subpool)
	Returns the EM event-pool and subpool the event was allocated from.

em_status_t	em_event_set_type (em_event_t event, em_event_type_t newtype)

em_event_type_t	em_event_type (em_event_t event)

int	em_event_type_multi (const em_event_t events[], int num, em_event_type_t types[])

int	em_event_same_type_multi (const em_event_t events[], int num, em_event_type_t *same_type)

em_status_t	em_event_mark_send (em_event_t event, em_queue_t queue)

em_status_t	em_event_unmark_send (em_event_t event)

void	em_event_mark_free (em_event_t event)
	Mark the event as "free".

void	em_event_unmark_free (em_event_t event)
	Unmark an event previously marked as "free" (i.e mark as "allocated" again).

void	em_event_mark_free_multi (const em_event_t events[], int num)
	Mark multiple events as "free".

void	em_event_unmark_free_multi (const em_event_t events[], int num)
	Unmark multiple events previously marked as "free".

em_event_t	em_event_clone (em_event_t event, em_pool_t pool)
	Clone an event.

em_event_t	em_event_clone_part (em_event_t event, em_pool_t pool, uint32_t offset, uint32_t len, bool clone_uarea)
	Partially clone an event.

uint64_t	em_event_to_u64 (em_event_t event)

Detailed Description

Operations on an event.

All application processing is driven by events in the Event Machine. An event describes a piece of work or data to be processed. The structure of an event is event type specific: it may be a directly accessible buffer of memory, packet headers and data, a vector or user specified content etc.

Applications use the event type to interpret the event structure. The event type consists of a major and a minor part: the major part specifies the actual type or structure of the event (sw buf, packet, vector etc.) while the minor part is user specific and can be used to distinguish between different use cases of the event.

Events follow message passing semantics: an event has to be allocated using the provided API (em_alloc()) or received through queues by an EO callback function after which the event is owned by the application. Event ownership is transferred back to the system by using em_send() or em_free(). An event not owned by the application must not be touched.

The event handle, of type em_event_t, is not a direct pointer to the event structure, hence EM API functions must be used to get access to the contained data: for events of (major) type sw buffer or packet use em_event_pointer() while for vector events the contained array of event handles must be accessed with em_event_vector_tbl() instead. Use the (major part of the) event type to distinguish between vectors and other types of events.

Macro Definition Documentation

◆ em_event_get_pool

#define em_event_get_pool em_event_pool

Definition at line 511 of file event_machine_event.h.

◆ em_event_get_pool_subpool

#define em_event_get_pool_subpool em_event_pool_subpool

Definition at line 535 of file event_machine_event.h.

◆ em_event_get_size

#define em_event_get_size em_event_size

Definition at line 493 of file event_machine_event.h.

◆ em_event_get_type

#define em_event_get_type em_event_type

Definition at line 588 of file event_machine_event.h.

◆ em_event_get_type_multi

#define em_event_get_type_multi em_event_type_multi

Definition at line 657 of file event_machine_event.h.

◆ em_get_type_major

#define em_get_type_major em_event_type_major

Definition at line 607 of file event_machine_event.h.

◆ em_get_type_minor

#define em_get_type_minor em_event_type_minor

Definition at line 629 of file event_machine_event.h.

Typedef Documentation

◆ em_event_type_major_e

typedef enum em_event_type_major_e em_event_type_major_e

Non-EM Events

Event (major) Type: EM_EVENT_TYPE_ODP

EM can pass through and offer limited functionality to ODP events of types that are not natively supported by EM. These non-EM events originate from event pools that are not created by EM. Non-EM events don't have an EM event header and therefore, e.g., ESV is not used with them. These events can be sent to EM queues, dequeued from unscheduled EM queues and freed. The EM event type of a non-EM event is reported as 'EM_EVENT_TYPE_ODP'. To use a non-EM event with ODP functions, the event must first be converted to an ODP event with em_odp_event2odp() (or em_odp_events2odp()). Non-EM events received by a user EO-receive function can be handled by inspecting the event type given as a receive function argument and comparing it to 'EM_EVENT_TYPE_ODP', converting it to an ODP event and then processing it via ODP APIs. Major event types used by em_event_type_t

Enumeration Type Documentation

◆ em_event_type_major_e

enum em_event_type_major_e

Non-EM Events

Event (major) Type: EM_EVENT_TYPE_ODP

EM can pass through and offer limited functionality to ODP events of types that are not natively supported by EM. These non-EM events originate from event pools that are not created by EM. Non-EM events don't have an EM event header and therefore, e.g., ESV is not used with them. These events can be sent to EM queues, dequeued from unscheduled EM queues and freed. The EM event type of a non-EM event is reported as 'EM_EVENT_TYPE_ODP'. To use a non-EM event with ODP functions, the event must first be converted to an ODP event with em_odp_event2odp() (or em_odp_events2odp()). Non-EM events received by a user EO-receive function can be handled by inspecting the event type given as a receive function argument and comparing it to 'EM_EVENT_TYPE_ODP', converting it to an ODP event and then processing it via ODP APIs. Major event types used by em_event_type_t

Enumerator
EM_EVENT_TYPE_UNDEF	Undef event type
EM_EVENT_TYPE_SW	SW event
EM_EVENT_TYPE_PACKET	Packet event
EM_EVENT_TYPE_TIMER	Timer event
EM_EVENT_TYPE_CRYPTO	Crypto event
EM_EVENT_TYPE_VECTOR	Event is a vector, contains an event table
EM_EVENT_TYPE_TIMER_IND	Ring timer: read-only, no-payload periodic timeout indication. Only the ring timer should set this type, the user must never set this type manually via em_alloc...() or em_event_set_type().
EM_EVENT_TYPE_ODP	Non EM event type with limited functionality compared to EM event types
EM_EVENT_TYPE_ANY	Any event type (used e.g. for event vector table content)

Definition at line 191 of file event_machine_event.h.

◆ em_event_type_sw_minor_e

enum em_event_type_sw_minor_e

Minor event types for the major EM_EVENT_TYPE_SW type.

Definition at line 229 of file event_machine_event.h.

Function Documentation

◆ em_alloc()

em_event_t em_alloc	(	uint32_t	size,
		em_event_type_t	type,
		em_pool_t	pool
	)

Allocate an event.

Allocate a new event from the given pool. The pool used must support events of the requested (major) type:

Events of (major) type EM_EVENT_TYPE_SW can be allocated from pools created to support event types EM_EVENT_TYPE_SW or EM_EVENT_TYPE_PACKET.
Events of (major) type EM_EVENT_TYPE_PACKET can be allocated from pools created to support the event type EM_EVENT_TYPE_PACKET.
Event vectors of (major) type EM_EVENT_TYPE_VECTOR can be allocated from pools created to support the event type EM_EVENT_TYPE_VECTOR.

The memory address of the allocated event is system specific and can depend on the given pool, event size and type. The returned event (handle) may refer to a memory buffer, packet or vector etc., i.e. the event structure is event type specific.

Use em_event_pointer(), or for vectors em_event_vector_tbl(), to convert an event (handle) to a pointer to the event payload or access the vector table. EM does not initialize the payload data.

Concerning events and pools of type EM_EVENT_TYPE_SW or EM_EVENT_TYPE_PACKET:

EM_EVENT_TYPE_SW with minor type '0' is reserved for direct portability - it is always guaranteed to produce an event with contiguous payload that can directly be used by the application up to the given size (no HW specific descriptors etc. are visible). This event payload will be 64-bit aligned by default (unless explicitly configured otherwise).
EM_POOL_DEFAULT can be used as a pool handle if there's no need to use a specific event pool (up to the size- or event limits of that pool).

Additionally it is guaranteed, that two separate buffers never share a cache line (to avoid false sharing).

Note: Vector events must always have their major event type set to EM_EVENT_TYPE_VECTOR or EM will not recognize them as vectors. Also, the event type for periodic timer ring events, EM_EVENT_TYPE_TIMER_IND, must NOT be used with em_alloc().

Parameters

size	1) Packet & sw-buf: event size in bytes (B), size > 0. 2) Vector: number of event handles that should fit into the vector table of the event, size > 0.
type	Event type to allocate. The event major-type must be supported by given 'pool'. Vector events must be allocated with major type EM_EVENT_TYPE_VECTOR from a pool created to support vectors.
pool	Event pool handle. The pool must have been created to support events of type 'em_event_type_major(type)'

Returns: The allocated event or EM_EVENT_UNDEF on error.

See also: em_free(), em_send(), em_event_pointer(), em_receive_func_t, em_event_clone() etc.; additionally for vector events: em_event_vector_tbl(), em_event_vector_free() etc.

Definition at line 67 of file event_machine_event.c.

◆ em_alloc_multi()

int em_alloc_multi	(	em_event_t	events[],
		int	num,
		uint32_t	size,
		em_event_type_t	type,
		em_pool_t	pool
	)

Allocate multiple events.

Similar to em_alloc(), but allows allocation of multiple events, with same properties, with one function call. The em_alloc_multi() API function will try to allocate the requested number ('num') of events but may fail to do so, e.g. if the pool has run out of events, and will return the actual number of events that were successfully allocated from the given pool.

Note: Vector events must always have their major event type set to EM_EVENT_TYPE_VECTOR or EM will not recognize them as vectors. Also, the event type for periodic timer ring events, EM_EVENT_TYPE_TIMER_IND, must NOT be used with em_alloc_multi().

Parameters

[out]	events	Output event array, events are allocated and filled by em_alloc_multi(). The given array must fit 'num' events.
	num	Number of events to allocate and write into 'events[]'
	size	1) Packet & sw-buf: event size in bytes (B), size > 0. 2) Vector: number of event handles that should fit into the vector table of the event, size > 0.
	type	Event type to allocate. The event major-type must be supported by given 'pool'. Vector events must be allocated with major type EM_EVENT_TYPE_VECTOR from a pool created to support vectors.
	pool	Event pool handle. The pool must have been created to support events of type 'em_event_type_major(type)'

Returns: Number of events actually allocated from the pool (0 ... num) and written into the output array 'events[]'.

See also: em_alloc() for more documentation.

Examples: bench_event.c, loop_united.c, and pool_perf.c.

Definition at line 127 of file event_machine_event.c.

◆ em_event_clone()

em_event_t em_event_clone	(	em_event_t	event,
		em_pool_t	pool
	)

Clone an event.

Allocate a new event with identical payload to the given event. The major type of the event to be cloned must be EM_EVENT_TYPE_SW or EM_EVENT_TYPE_PACKET, e.g. cloning a vector event is not supported.

If present, the event user area is also cloned. Note that if a 'pool' is given and it has been configured to provide a smaller user area for events than the pool the original event was allocated from, then the clone operation will fail, returning EM_EVENT_UNDEF. Thus make sure to use compatible pools for cloning. Using the same pool ('pool' == EM_POOL_UNDEF) will always be compatible with respect of the user area sizing.

Note: Other event metadata, internal headers and state are NOT cloned (e.g. the event-group of a cloned event is EM_EVENT_GROUP_UNDEF etc).

Parameters

event	Event to be cloned, must be a valid event.
pool	Optional event pool to allocate the cloned event from. Use 'EM_POOL_UNDEF' to clone from the same pool as 'event' was allocated from. The event-type of 'event' must be suitable for allocation from 'pool' (e.g. EM_EVENT_TYPE_PACKET can not be allocated from a pool supporting only EM_EVENT_TYPE_SW) The user area size of events from 'pool' must be large enough to fit the cloned user area.

Returns: The cloned event handle

Return values

EM_EVENT_UNDEF on error

See also: em_alloc(), em_free()

Examples: bench_event.c.

Definition at line 1552 of file event_machine_event.c.

◆ em_event_clone_part()

em_event_t em_event_clone_part	(	em_event_t	event,
		em_pool_t	pool,
		uint32_t	offset,
		uint32_t	len,
		bool	clone_uarea
	)

Partially clone an event.

Allocate a new event (of size 'len') and copy 'len' bytes of data starting from 'offset' from the given event into the new event. The maximum number of bytes to copy is event-size minus the offset. The major type of the event to be (partially) cloned must be EM_EVENT_TYPE_SW or EM_EVENT_TYPE_PACKET, e.g. cloning a vector event is not supported.

If present, and 'clone_uarea = true', the event user area is also cloned. Note that if a 'pool' is given and it has been configured to provide a smaller user area for events than the pool the original event was allocated from, then the clone operation will fail, returning EM_EVENT_UNDEF. Thus make sure to use compatible pools for cloning. Using the same pool ('pool' == EM_POOL_UNDEF) will always be compatible with respect of the user area sizing.

Note: Other event metadata, internal headers and state are NOT cloned (e.g. the event-group of a cloned event is EM_EVENT_GROUP_UNDEF etc).

Parameters

event	Event to be cloned, must be a valid event.
pool	Optional event pool to allocate the partially cloned event from. Use 'EM_POOL_UNDEF' to clone from the same pool as 'event' was allocated from. The event-type of 'event' must be suitable for allocation from 'pool' (e.g. EM_EVENT_TYPE_PACKET can not be allocated from a pool supporting only EM_EVENT_TYPE_SW). The user area size of events from 'pool' must be large enough to fit the cloned user area (if 'clone_uarea = true').
offset	Byte offset into the event payload
len	Number of bytes to copy/clone.
clone_uarea	Set 'true' to also clone the event user area (true/false).

Returns: The partially cloned event or EM_EVENT_UNDEF on error.

See also: em_alloc(), em_free()

Examples: bench_event.c.

Definition at line 1557 of file event_machine_event.c.

◆ em_event_mark_free()

void em_event_mark_free ( em_event_t event )

Mark the event as "free".

Indicates a user-given promise to EM that the event will be freed back into the pool it was allocated from e.g. by HW or device drivers (external to EM). Calling em_event_mark_free() transfers event ownership away from the user, and thus the event must not be used or touched by the user anymore.

Example use case: A user provided output-callback function associated with a queue of type 'EM_QUEUE_TYPE_OUTPUT' can use this API when configuring a HW-device or device-driver to free the event (outside of EM) after transmission.

EM will, after this API-call, treat the event as "freed" and any further API operations or usage might lead to EM errors (depending on the error-check level), e.g. em_send/free/tmo_set/ack(event) etc. is forbidden after em_event_mark_free(event).

Note: Registered API-callback hooks for em_free/_multi() (em_api_hook_free_t) will NOT be called.

Parameters

event Event to be marked as "free"

See also: em_free(), em_event_unmark_free()

Examples: event_types.c.

Definition at line 1211 of file event_machine_event.c.

◆ em_event_mark_free_multi()

void em_event_mark_free_multi	(	const em_event_t	events[],
		int	num
	)

Mark multiple events as "free".

Similar to em_event_mark_free(), but allows the marking of multiple events as "free" with one function call.

Note: Registered API-callback hooks for em_free/_multi() (em_api_hook_free_t) will NOT be called.

Parameters

[in]	events	Array of events to be marked as "free"
	num	The number of events in the array 'events[]'

Examples: event_types.c.

Definition at line 1268 of file event_machine_event.c.

◆ em_event_mark_send()

em_status_t em_event_mark_send	(	em_event_t	event,
		em_queue_t	queue
	)

Mark the event as "sent".

Indicates a user-given promise to EM that the event will later appear into 'queue' by some means other than an explicit user call to em_send...(). Calling em_event_mark_send() transfers event ownership away from the user, and thus the event must not be used or touched by the user anymore (the only exception is (hw) error recovery where the "sent" state can be cancelled by using em_event_unmark_send() - dangerous!).

Example use case: A user provided output-callback function associated with a queue of type 'EM_QUEUE_TYPE_OUTPUT' can use this API when configuring a HW-device to deliver the event back into EM. The HW will eventually "send" the event and it will "somehow" again appear into EM for the user to process.

EM will, after this API-call, treat the event as "sent" and any further API operations or usage might lead to EM errors (depending on the error-check level), e.g. em_send/free/tmo_set/ack(event) etc. is forbidden after em_event_mark_send(event).

Note: Registered API-callback hooks for em_send...() (em_api_hook_send_t) will NOT be called.; Marking an event "sent" with an event group (corresponding to em_send_group()) is currently NOT supported.

Parameters

event	Event to be marked as "sent"
queue	Destination queue (must be scheduled, i.e. atomic, parallel or ordered)

Returns: EM_OK if successful

See also: em_send(), em_event_unmark_send()

Examples: event_types.c.

Definition at line 1137 of file event_machine_event.c.

◆ em_event_pointer()

void * em_event_pointer ( em_event_t event )

Get a pointer to the event structure/data.

Returns a pointer to the beginning of the event data or NULL in case of error. The structure/content of the event data is user and/or event type specific. It may be a directly accessible buffer of memory, contain packet headers and data or have user specified content etc. Use em_event_type() and em_event_type_major() to determine the type of the event.

Note: em_event_pointer() should NOT be used with events of (major) type EM_EVENT_TYPE_VECTOR or EM_EVENT_TYPE_TIMER_IND - usage with these types of events returns NULL and an error is reported. Instead, when dealing with event vectors, use em_event_vector_tbl() to get access to the vector table. Further, periodic timer-ring timeout indication events have no user accessible payload.

Parameters

event Event handle

Returns: Pointer to the beginning of the event data

Return values

NULL	on unsupported event type or other error

See also: em_event_vector_tbl() when dealing with vector events.

Definition at line 833 of file event_machine_event.c.

◆ em_event_pointer_and_size()

void * em_event_pointer_and_size	(	em_event_t	event,
		uint32_t *	size
	)

Get a pointer to the event structure/data as well as the event size.

Returns a pointer to the beginning of the event data as well as the event type specific payload size via the output arg 'size'.

This API is a combination of em_event_pointer() and em_event_size() since both are often needed, especially in the EO-receive function where event payload manipulation naturally takes place.

The structure/content of the event data is user and/or event type specific. It may be a directly accessible buffer of memory, contain packet headers and data or have user specified content etc. Use em_event_type() to determine the type of the event or rely on the 'type' argument provided to the EO-receive function (em_receive_func_t). Use em_event_type_major() to get the major part of the event type.

Note: Do not use this API function for vector events (major event type EM_EVENT_TYPE_VECTOR) or periodic timer ring timeout events (event type EM_EVENT_TYPE_TIMER_IND). Instead, for vectors use the em_event_vector_...() APIs. Timer ring timeout events have no user accessible data.

Parameters

	event	Event handle
[out]	size	Optional output arg into which the event type specific payload size (in bytes) is stored. Use 'size=NULL' if no size information is needed. Only set by the function when no errors occurred. For events of (major) type sw buf or packet the size is the available buffer/payload size in bytes (B).

Returns: Pointer to the beginning of the event data

Return values

NULL	on unsupported event type or other error ('size' not touched)

See also: em_event_pointer(), em_event_size()

Examples: bench_event.c.

Definition at line 850 of file event_machine_event.c.

◆ em_event_pool()

em_pool_t em_event_pool ( em_event_t event )

Returns the EM event-pool the event was allocated from.

The EM event-pool for the given event can only be obtained if the event has been allocated from a pool created with em_pool_create(). For other pools, e.g. external (to EM) pktio pools, EM_POOL_UNDEF is returned.

Parameters

event Event handle

Returns: The EM event-pool handle or EM_POOL_UNDEF if no EM pool is found. EM_POOL_UNDEF is returned also for a valid event that has been allocated from a pool external to EM (no error is reported).

Examples: bench_event.c.

Definition at line 938 of file event_machine_event.c.

◆ em_event_pool_subpool()

em_pool_t em_event_pool_subpool	(	em_event_t	event,
		int *	subpool
	)

Returns the EM event-pool and subpool the event was allocated from.

Similar to em_event_pool(), but also outputs the subpool the event was allocated from. The subpool is in the range [0, EM_MAX_SUBPOOLS - 1].

Parameters

	event	Event handle
[out]	subpool	Subpool index, output arg filled on successful return. Use 'NULL' if not interested in the subpool (or prefer em_event_pool() instead). The subpool is filled only when a valid EM pool can be found, i.e. when the return value is other than EM_POOL_UNDEF - EM doesn't touch it otherwise.

Returns: The EM event-pool handle or EM_POOL_UNDEF if no EM pool is found. EM_POOL_UNDEF is returned also for a valid event that has been allocated from a pool external to EM (no error is reported).

Examples: bench_event.c.

Definition at line 961 of file event_machine_event.c.

◆ em_event_same_type_multi()

int em_event_same_type_multi	(	const em_event_t	events[],
		int	num,
		em_event_type_t *	same_type
	)

Get the number of events that have the same event type.

Returns the number of consecutive events from the start of the array 'events[]' that have the same event type. Outputs that same event type. Useful for iterating through an event-array and grouping by event type.

Parameters

	events	Event handles: events[num]
	num	Number of events. The array 'events[]' must contain 'num' entries.
[out]	same_type	Event type pointer for output

Returns: Number of consecutive events (0...num) with the same event type (return value always >=0), includes and starts from events[0]. The return value is usually '>=1' and thus '0' is only seen in error scenarios when the type of the first event could not be obtained or if the given 'num=0'. The function stops and returns on the first error.

Examples: bench_event.c.

Definition at line 1097 of file event_machine_event.c.

◆ em_event_set_type()

em_status_t em_event_set_type	(	em_event_t	event,
		em_event_type_t	newtype
	)

Set the event type of an event

The operation may fail if (the major part of) the new type is not compatible with the old one. EM does not check the compatibility of the new vs. old event type for all cases, thus the user must take care not to incorrectly update the type.

Note: Vector events must always have their major type set to EM_EVENT_TYPE_VECTOR or EM will not recognize them as vectors. Also, timer ring events must always have their event type set to EM_EVENT_TYPE_TIMER_IND or EM will not recognize them as periodic timer ring timeout events. Trying to set an incorrect type for these events result in error.

Parameters

event	Event handle
newtype	New type for the event

Returns: EM_OK on success

See also: em_alloc(), em_event_type/_multi(), em_event_type_major(), em_event_type_minor(), em_receive_func_t(..., em_event_type_t type, ...)

Examples: bench_event.c.

Definition at line 985 of file event_machine_event.c.

◆ em_event_size()

uint32_t em_event_size ( em_event_t event )

Returns the event payload size in bytes (B) of the given event

Returns the event type specific payload size of the event. For events of (major) type sw buf or packet the size is the available buffer/payload size in bytes (B).

Note: Do not use this API function for vector events, instead use em_event_vector_size(), em_event_vector_max_size() or em_event_vector_info(). Use the event type to distinguish between vectors and other types of events.

Parameters

event Event handle

Returns: Event type specific payload size in bytes.

Examples: bench_event.c, queues.c, queues_local.c, queues_output.c, queues_unscheduled.c, and send_multi.c.

Definition at line 901 of file event_machine_event.c.

◆ em_event_to_u64()

uint64_t em_event_to_u64 ( em_event_t event )

Convert an event handle to an unsigned integer

Parameters

event Event handle to be converted

Returns: uint64_t value that can be used to print/display the handle

Note: This routine is intended to be used for diagnostic purposes to enable applications to e.g. generate a printable value that represents an em_event_t handle.

Definition at line 2199 of file event_machine_event.c.

◆ em_event_type()

em_event_type_t em_event_type ( em_event_t event )

Get the event type of an event

Returns the type of the given event. The type has been set by em_alloc...(), em_event_set_type() or e.g. packet input.

Note that the event type consists of a major and a minor part. The major part specifies the actual type or structure of the event (sw buf, packet, vector etc.) while the minor part is user specific and can be used to distinguish between different use cases of the event. Use em_event_type_major() and em_event_type_minor() to get the major and minor parts of the event type.

Parameters

event Event handle

Returns: event type

Return values

EM_EVENT_TYPE_UNDEF on error

See also: em_alloc(), em_event_set_type(), em_event_type_major(), em_event_type_minor(), em_receive_func_t(..., em_event_type_t type, ...)

Examples: bench_event.c.

Definition at line 1045 of file event_machine_event.c.

◆ em_event_type_multi()

int em_event_type_multi	(	const em_event_t	events[],
		int	num,
		em_event_type_t	types[]
	)

Get the event types of multiple events

Writes the event type of each given event into an output type-array and returns the number of entries written. Note, if 'events[num]' are all of the same type then 'types[num]' will contain 'num' same entries.

Parameters

	events	Event handles: events[num]
	num	Number of events and output types. The array 'events[]' must contain 'num' entries and the output array 'types[]' must have room for 'num' entries.
[out]	types	Event types (output array): types[num] (types[i] is the type of events[i])

Returns: Number of event types (0...num) written into 'types[]'. The return value (always >=0) is usually 'num' and thus '<num' is only seen in error scenarios when the type of event[i] could not be obtained. The return value will be '0' in error cases or if the given 'num=0'. The function stops and returns on the first error and will not fill the rest of 'types[]'.

Examples: bench_event.c.

Definition at line 1058 of file event_machine_event.c.

◆ em_event_unmark_free()

void em_event_unmark_free ( em_event_t event )

Unmark an event previously marked as "free" (i.e mark as "allocated" again).

Note: This is for recovery situations only and can potentially crash the application if used incorrectly! Unmarking the free-state of an event that has already been freed will lead to fatal error.

Revert an event's "free" state, as set by em_event_mark_free(), back to the state before the mark-free function call. Any further usage of the event after em_event_mark_free(), by EM or the user, will result in error when calling em_event_unmark_free() since the state has become unrecoverable. => the only allowed EM API call after em_event_mark_free() (for a certain event) is em_event_unmark_free() when it is certain that the event, due to some external error, will not be freed otherwise and must be recovered back into the EM-domain so that calling em_free() by the user is possible. Calling em_event_unmark_free() transfers event ownership back to the user again.

Note: Unmark-send and unmark-free are the only valid cases of using an event that the user no longer owns - all other such uses leads to fatal error

em_status_t err;
hw_err_t hw_err;
 
// 'event' owned by the user
em_event_mark_free(event);
// 'event' no longer owned by the user - don't touch!
 
hw_err = config_hw_to_transmit_event(...hw-cfg..., event);
if (hw_err) {
   // hw config error - the event can be recovered if it is
   // certain that the hw won't free that same event.
   // note: the user doesn't own the event here and actually
   //       uses an obsolete event handle to recover the event.
   em_event_unmark_free(event);
   // 'event' recovered, again owned by the user
   em_free(event);
}

Parameters

event Event previously marked as "free" with em_event_mark_free/_multi(), any other use case is invalid!

See also: em_free(), em_event_mark_free()

Examples: event_types.c.

Definition at line 1240 of file event_machine_event.c.

◆ em_event_unmark_free_multi()

void em_event_unmark_free_multi	(	const em_event_t	events[],
		int	num
	)

Unmark multiple events previously marked as "free".

Note: This is for recovery situations only and can potentially crash the application if used incorrectly!

Similar to em_event_unmark_free(), but allows to do the "free"-unmarking of multiple events with one function call.

Parameters

[in]	events	Events previously marked as "free" with em_event_mark_free/_multi(), other use cases are invalid!
	num	The number of events in the array 'events[]'

Examples: event_types.c.

Definition at line 1317 of file event_machine_event.c.

◆ em_event_unmark_send()

em_status_t em_event_unmark_send ( em_event_t event )

Unmark an event previously marked as "sent" (i.e mark as "unsent")

Note: This is for recovery situations only and can potentially crash the application if used incorrectly!

Revert an event's "sent" state, as set by em_event_mark_send(), back to the state before the mark-send function call. Any further usage of the event after em_event_mark_send(), by EM or the user, will result in error when calling em_event_unmark_send() since the state has become unrecoverable. => the only allowed EM API call after em_event_mark_send() is em_event_unmark_send() if it is certain that the event, due to some external error, will never be sent into EM again otherwise. Calling em_event_unmark_send() transfers event ownership back to the user again.

Note: Unmark-send and unmark-free are the only valid cases of using an event that the user no longer owns - all other such uses leads to fatal error

em_status_t err;
hw_err_t hw_err;
 
// 'event' owned by the user
err = em_event_mark_send(event, queue);
if (err != EM_OK)
   return err; // NOK
// 'event' no longer owned by the user - don't touch!
 
hw_err = config_hw_to_send_event(...hw-cfg..., event, queue);
if (hw_err) {
   // hw config error - the event can be recovered if it is
   // certain that the hw won't send that same event.
   // note: the user doesn't own the event here and actually
   //       uses an obsolete event handle to recover the event.
   err = em_event_unmark_send(event);
   if (err != EM_OK)
           return err; // NOK
   // 'event' recovered, again owned by the user
   em_free(event);
}

Parameters

event Event previously marked as "sent" with em_event_mark_send(), any other case will be invalid!

Returns: EM_OK if successful

See also: em_send(), em_event_mark_send()

Examples: event_types.c.

Definition at line 1185 of file event_machine_event.c.

◆ em_free()

void em_free ( em_event_t event )

Free an event.

The em_free() function transfers ownership of the event back to the system and the application must not touch the event (or related memory buffers) after calling it.

It is assumed that the implementation can detect the event pool that the event was originally allocated from.

The application must only free events it owns. For example, the sender must not free an event after sending it.

Note: Freeing a vector event (of type EM_EVENT_VECTOR) with this API will also free the events contained in the vector's event-table. To free only the vector event itself, use em_event_vector_free().

Parameters

event Event to be freed

See also: em_alloc(), em_free_multi(), em_event_vector_free()

Definition at line 336 of file event_machine_event.c.

◆ em_free_multi()

void em_free_multi	(	em_event_t	events[],
		int	num
	)

Free multiple events.

Similar to em_free(), but allows freeing of multiple events with one function call. The application must not touch the given events after a call to em_free_multi().

Note: Freeing vector events (of type EM_EVENT_VECTOR) with this API will also free the events contained in the vectors' event-table. To free only the vector event itself, use em_event_vector_free().

Parameters

[in]	events	Array of events to be freed
	num	The number of events in the array 'events[]'

Examples: bench_event.c, loop_united.c, pool_perf.c, queues_unscheduled.c, and send_multi.c.

Definition at line 447 of file event_machine_event.c.

◆ em_send()

em_status_t em_send	(	em_event_t	event,
		em_queue_t	queue
	)

Send an event to a queue.

The event must have been allocated with em_alloc(), or received via an EO receive-function. The sender must not touch the event after calling em_send() as the ownership has been transferred to the system or possibly to the next receiver. If the return status is not EM_OK, the ownership has not been transferred and the application is still responsible for the event (e.g. may free it).

EM does not currently define guaranteed event delivery, i.e. EM_OK return value only means the event was accepted for delivery. It could still be lost during delivery (e.g. due to a removed queue or system congestion, etc).

Parameters

event	Event to be sent
queue	Destination queue

Returns: EM_OK if successful (accepted for delivery).

See also: em_alloc()

Definition at line 744 of file event_machine_event.c.

◆ em_send_multi()

int em_send_multi	(	const em_event_t	events[],
		int	num,
		em_queue_t	queue
	)

Send multiple events to a queue.

As em_send, but multiple events can be sent with one call for potential performance gain. The function returns the number of events actually sent. A return value equal to the given 'num' means that all events were sent. A return value less than 'num' means that only the first 'num' events were sent and the rest must be handled by the application.

Parameters

events	Array of events to send
num	Number of events. The array 'events[]' must contain 'num' entries.
queue	Destination queue

Returns: number of events successfully sent (equal to num if all successful)

See also: em_send()

Examples: atomic_processing_end.c, bench_event.c, event_types.c, fractal.c, loop_united.c, ordered.c, queue_types_ag.c, queue_types_local.c, queues_unscheduled.c, and send_multi.c.

Definition at line 793 of file event_machine_event.c.

Modules

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ em_event_get_pool

◆ em_event_get_pool_subpool

◆ em_event_get_size

◆ em_event_get_type

◆ em_event_get_type_multi

◆ em_get_type_major

◆ em_get_type_minor

Typedef Documentation

◆ em_event_type_major_e

Non-EM Events

Enumeration Type Documentation

◆ em_event_type_major_e

Non-EM Events

◆ em_event_type_sw_minor_e

Function Documentation

◆ em_alloc()

◆ em_alloc_multi()

◆ em_event_clone()

◆ em_event_clone_part()

◆ em_event_mark_free()

◆ em_event_mark_free_multi()

◆ em_event_mark_send()

◆ em_event_pointer()

◆ em_event_pointer_and_size()

◆ em_event_pool()

◆ em_event_pool_subpool()

◆ em_event_same_type_multi()

◆ em_event_set_type()

◆ em_event_size()

◆ em_event_to_u64()

◆ em_event_type()

◆ em_event_type_multi()

◆ em_event_unmark_free()

◆ em_event_unmark_free_multi()

◆ em_event_unmark_send()

◆ em_free()

◆ em_free_multi()

◆ em_send()

◆ em_send_multi()