Operations on queue groups. More...

Functions
em_queue_group_t	em_queue_group_create (const char name, const em_core_mask_t mask, int num_notif, const em_notif_t notif_tbl[])

em_queue_group_t	em_queue_group_create_sync (const char name, const em_core_mask_t mask)

em_status_t	em_queue_group_delete (em_queue_group_t queue_group, int num_notif, const em_notif_t notif_tbl[])

em_status_t	em_queue_group_delete_sync (em_queue_group_t queue_group)

em_status_t	em_queue_group_modify (em_queue_group_t queue_group, const em_core_mask_t *new_mask, int num_notif, const em_notif_t notif_tbl[])

em_status_t	em_queue_group_modify_sync (em_queue_group_t queue_group, const em_core_mask_t *new_mask)

em_queue_group_t	em_queue_group_find (const char *name)

em_status_t	em_queue_group_get_mask (em_queue_group_t queue_group, em_core_mask_t *mask)

size_t	em_queue_group_get_name (em_queue_group_t queue_group, char *name, size_t maxlen)

em_queue_group_t	em_queue_group_get_first (unsigned int *num)

em_queue_group_t	em_queue_group_get_next (void)

em_queue_t	em_queue_group_queue_get_first (unsigned int *num, em_queue_group_t queue_group)

em_queue_t	em_queue_group_queue_get_next (void)

uint64_t	em_queue_group_to_u64 (em_queue_group_t queue_group)

Detailed Description

Operations on queue groups.

A queue group is basically a set of cores (threads) within an EM instance allowed to receive events from a queue belonging to that queue group.

Function Documentation

◆ em_queue_group_create()

em_queue_group_t em_queue_group_create	(	const char *	name,
		const em_core_mask_t *	mask,
		int	num_notif,
		const em_notif_t	notif_tbl[]
	)

Create a new queue group to control queue to core mapping, asynchronous (non-blocking)

Allocates a new queue group handle with a given core mask. Cores added to the queue group can be changed later with em_queue_group_modify().

This operation may be asynchronous, i.e. the creation may complete well after this function has returned. Provide notification events, if the application needs to know about the actual completion. EM will send notifications when the operation has completed. Note that using a queue group before the creation has completed may result in undefined behaviour.

The core mask is visible through em_queue_group_get_mask() only after the create operation has completed.

Note, that the operation can also happen one core at a time, so an intermediate mask may be active momentarily.

Only manipulate the core mask with the access macros defined in event_machine_hw_specific.h as the implementation underneath may change.

The given name is copied up to the maximum length of EM_QUEUE_GROUP_NAME_LEN. Duplicate names are allowed, but find will then only return the first match. The name "default" is reserved for EM_QUEUE_GROUP_DEFAULT.

EM has a default group EM_QUEUE_GROUP_DEFAULT containing all cores running this EM instance. It's named "default".

Some systems may have a low number of queue groups available.

Attention: Only call em_queue_create() after em_queue_group_create() has completed - use notifications to synchronize. Alternatively use em_queue_group_create_sync() to be able to create the queue directly after creating the queue group in the source code.

Parameters

name	Queue group name (optional, NULL ok)
mask	Core mask for the queue group
num_notif	Number of entries in notif_tbl (use 0 for no notification)
notif_tbl	Array of notifications to send as the operation completes

Returns: Queue group or EM_QUEUE_GROUP_UNDEF on error.

See also: em_queue_group_find(), em_queue_group_modify(), em_queue_group_delete(), em_queue_group_create_sync()

Examples: queue_group.c, and queue_groups.c.

Definition at line 40 of file event_machine_queue_group.c.

◆ em_queue_group_create_sync()

em_queue_group_t em_queue_group_create_sync	(	const char *	name,
		const em_core_mask_t *	mask
	)

Create a new queue group to control queue to core mapping, synchronous (blocking).

As em_queue_group_create(), but will not return until the operation is complete.

Note that the function is blocking and will not return until the operation has completed across all concerned EM cores. Sync-API calls can block the core for a long (indefinite) time, thus they should not be used to make runtime changes on real time EM cores - consider the async variants of the APIs in these cases instead. While one core is calling a sync-API function, the others must be running the EM dispatch loop to be able to receive and handle the sync-API request events sent internally. Use the sync-APIs mainly to simplify application start-up or teardown.

Parameters

name	Queue group name (optional, NULL ok)
mask	Core mask for the queue group

Returns: Queue group or EM_QUEUE_GROUP_UNDEF on error.

See also: em_queue_group_create() for an asynchronous version of the API

Examples: scheduling_latency.c, and timer_test_periodic.c.

Definition at line 76 of file event_machine_queue_group.c.

◆ em_queue_group_delete()

em_status_t em_queue_group_delete	(	em_queue_group_t	queue_group,
		int	num_notif,
		const em_notif_t	notif_tbl[]
	)

Delete the queue group, asynchronous (non-blocking)

Removes all cores from the queue group and free's the handle for re-use. All queues in the queue group must be deleted with em_queue_delete() before deleting the queue group.

Parameters

queue_group	Queue group to delete
num_notif	Number of entries in notif_tbl (0 for no notification)
notif_tbl	Array of notifications to send as the operation completes

Returns: EM_OK if successful.

See also: em_queue_group_create(), em_queue_group_modify(), em_queue_delete(), em_queue_group_delete_sync()

Examples: queue_group.c.

Definition at line 104 of file event_machine_queue_group.c.

◆ em_queue_group_delete_sync()

em_status_t em_queue_group_delete_sync ( em_queue_group_t queue_group )

Delete the queue group, synchronous (blocking).

As em_queue_group_delete(), but will not return until the operation is complete.

Note that the function is blocking and will not return until the operation has completed across all concerned EM cores. Sync-API calls can block the core for a long (indefinite) time, thus they should not be used to make runtime changes on real time EM cores - consider the async variants of the APIs in these cases instead. While one core is calling a sync-API function, the others must be running the EM dispatch loop to be able to receive and handle the sync-API request events sent internally. Use the sync-APIs mainly to simplify application start-up or teardown.

Parameters

queue_group Queue group to delete

Returns: EM_OK if successful.

See also: em_queue_group_delete() for an asynchronous version of the API

Definition at line 135 of file event_machine_queue_group.c.

◆ em_queue_group_find()

em_queue_group_t em_queue_group_find ( const char * name )

Finds a queue group by name.

Finds a queue group by the given name (exact match). An empty string will not match anything. The search is case sensitive. If there are duplicate names, this will return the first match only.

Parameters

name	Name of the queue qroup to find

Returns: Queue group or EM_QUEUE_GROUP_UNDEF if not found

See also: em_queue_group_create()

Examples: queue_group.c, and queue_groups.c.

Definition at line 236 of file event_machine_queue_group.c.

◆ em_queue_group_get_first()

em_queue_group_t em_queue_group_get_first ( unsigned int * num )

Initialize queue group iteration and return the first queue group handle.

Can be used to initialize the iteration to retrieve all created queue groups for debugging or management purposes. Use em_queue_group_get_next() after this call until it returns EM_QUEUE_GROUP_UNDEF. A new call to em_queue_group_get_first() resets the iteration, which is maintained per core (thread). The operation should be completed in one go before returning from the EO's event receive function (or start/stop).

The number of queue groups (output arg 'num') may not match the amount of queue groups actually returned by iterating using em_event_group_get_next() if queue groups are added or removed in parallel by another core. The order of the returned queue group handles is undefined.

unsigned int num;
em_queue_group_t qg = em_queue_group_get_first(&num);
while (qg != EM_QUEUE_GROUP_UNDEF) {
   qg = em_queue_group_get_next();
}

Parameters

[out] num Pointer to an unsigned int to store the amount of queue groups into

Returns: The first queue group handle or EM_QUEUE_GROUP_UNDEF if none exist

See also: em_queue_group_get_next()

Definition at line 333 of file event_machine_queue_group.c.

◆ em_queue_group_get_mask()

em_status_t em_queue_group_get_mask	(	em_queue_group_t	queue_group,
		em_core_mask_t *	mask
	)

Get the current core mask for a queue group.

This returns the situation at the moment of the inquiry. The result may not be up-to-date if another core is modifying the queue group at the same time. The application may need to synchronize group modifications.

Parameters

queue_group	Queue group
mask	Core mask for the queue group

Returns: EM_OK if successful.

See also: em_queue_group_create(), em_queue_group_modify()

Examples: queue_group.c, and timer_test_periodic.c.

Definition at line 260 of file event_machine_queue_group.c.

◆ em_queue_group_get_name()

size_t em_queue_group_get_name	(	em_queue_group_t	queue_group,
		char *	name,
		size_t	maxlen
	)

Get the name of a queue group.

A copy of the name string (up to 'maxlen' characters) is written to the user given buffer. The string is always null terminated, even if the given buffer length is less than the name length.

The function returns '0' and writes an empty string if the queue group has no name.

Parameters

	queue_group	Queue group id
[out]	name	Destination buffer
	maxlen	Maximum length (including the terminating '\0')

Returns: Number of characters written (excludes the terminating '\0').

Examples: queue_groups.c.

Definition at line 288 of file event_machine_queue_group.c.

◆ em_queue_group_get_next()

em_queue_group_t em_queue_group_get_next ( void )

Continues the queue group iteration started by em_queue_group_get_first() and returns the next queue group handle.

Returns: The next queue group handle or EM_QUEUE_GROUP_UNDEF if the queue group iteration is completed (i.e. no more queue groups available).

See also: em_queue_group_get_first()

Definition at line 363 of file event_machine_queue_group.c.

◆ em_queue_group_modify()

em_status_t em_queue_group_modify	(	em_queue_group_t	queue_group,
		const em_core_mask_t *	new_mask,
		int	num_notif,
		const em_notif_t	notif_tbl[]
	)

Modify the core mask of an existing queue group, asynchronous (non-blocking)

The function compares the new core mask to the current mask and changes the core mapping for the given queue group accordingly.

This operation may be asynchronous, i.e. the change may complete well after this function has returned. Provide notification events, if the application needs to know about the actual completion. EM will send notifications when the operation has completed.

The new core mask is visible through em_queue_group_get_mask() only after the modify operation has completed.

Note, that depending on the system, the change can also happen one core at a time, so an intermediate mask may be active momentarily.

Only manipulate core mask with the access macros defined in event_machine_hw_specific.h as the implementation underneath may change.

Parameters

queue_group	Queue group to modify
new_mask	New core mask
num_notif	Number of entries in notif_tbl (0 for no notification)
notif_tbl	Array of notifications to send as the operation completes

Returns: EM_OK if successful.

See also: em_queue_group_create(), em_queue_group_find(), em_queue_group_delete() em_queue_group_get_mask(), em_queue_group_modify_sync()

is_delete

Examples: queue_group.c.

Definition at line 161 of file event_machine_queue_group.c.

◆ em_queue_group_modify_sync()

em_status_t em_queue_group_modify_sync	(	em_queue_group_t	queue_group,
		const em_core_mask_t *	new_mask
	)

Modify core mask of an existing queue group, synchronous (blocking).

As em_queue_group_modify(), but will not return until the operation is complete.

Note that the function is blocking and will not return until the operation has completed across all concerned EM cores. Sync-API calls can block the core for a long (indefinite) time, thus they should not be used to make runtime changes on real time EM cores - consider the async variants of the APIs in these cases instead. While one core is calling a sync-API function, the others must be running the EM dispatch loop to be able to receive and handle the sync-API request events sent internally. Use the sync-APIs mainly to simplify application start-up or teardown.

Parameters

queue_group	Queue group to modify
new_mask	New core mask

Returns: EM_OK if successful.

See also: em_queue_group_modify() for an asynchronous version of the API

is_delete

Definition at line 201 of file event_machine_queue_group.c.

◆ em_queue_group_queue_get_first()

em_queue_t em_queue_group_queue_get_first	(	unsigned int *	num,
		em_queue_group_t	queue_group
	)

Initialize iteration of a queue group's queues and return the first queue handle.

Can be used to initialize the iteration to retrieve all queues associated with the given queue group for debugging or management purposes. Use em_queue_group_queue_get_next() after this call until it returns EM_QUEUE_UNDEF. A new call to em_queue_group_queue_get_first() resets the iteration, which is maintained per core (thread). The operation should be started and completed in one go before returning from the EO's event receive function (or start/stop).

The number of queues in the queue group (output arg 'num') may not match the amount of queues actually returned by iterating using em_queue_group_queue_get_next() if queues are added or removed in parallel by another core. The order of the returned queue handles is undefined.

Simplified example:

unsigned int num;
em_queue_t q = em_queue_group_queue_get_first(&num, queue_group);
while (q != EM_QUEUE_UNDEF) {
   q = em_queue_group_queue_get_next();
}

Parameters

[out]	num	Pointer to an unsigned int to store the amount of queue groups into.
	queue_group	Queue group handle

Returns: The first queue handle or EM_QUEUE_UNDEF if none exist or the queue group is invalid.

See also: em_queue_group_queue_get_next()

Definition at line 389 of file event_machine_queue_group.c.

◆ em_queue_group_queue_get_next()

em_queue_t em_queue_group_queue_get_next ( void )

Return the queue group's next queue handle.

Continues the queue iteration started by em_queue_group_queue_get_first() and returns the next queue handle in the queue group.

Returns: The next queue handle or EM_QUEUE_UNDEF if the queue iteration is completed (i.e. no more queues available for this queue group).

See also: em_queue_group_queue_get_first()

Definition at line 440 of file event_machine_queue_group.c.

◆ em_queue_group_to_u64()

uint64_t em_queue_group_to_u64 ( em_queue_group_t queue_group )

Convert a queue_group handle to an unsigned integer

Parameters

queue_group queue_group 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_queue_group_t handle.

Definition at line 464 of file event_machine_queue_group.c.

Functions

Detailed Description

Function Documentation

◆ em_queue_group_create()

◆ em_queue_group_create_sync()

◆ em_queue_group_delete()

◆ em_queue_group_delete_sync()

◆ em_queue_group_find()

◆ em_queue_group_get_first()

◆ em_queue_group_get_mask()

◆ em_queue_group_get_name()

◆ em_queue_group_get_next()

◆ em_queue_group_modify()

◆ em_queue_group_modify_sync()

◆ em_queue_group_queue_get_first()

◆ em_queue_group_queue_get_next()

◆ em_queue_group_to_u64()