Queue group

Macros
#define	em_queue_group_get_mask   em_queue_group_mask
#define	em_queue_group_get_name   em_queue_group_name
#define	em_queue_group_get_first   em_queue_group_first
#define	em_queue_group_get_next   em_queue_group_next
#define	em_queue_group_queue_get_first   em_queue_group_queue_first
#define	em_queue_group_queue_get_next   em_queue_group_queue_next

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_mask (em_queue_group_t queue_group, em_core_mask_t *mask)
size_t	em_queue_group_name (em_queue_group_t queue_group, char *name, size_t maxlen)
em_queue_group_t	em_queue_group_first (unsigned int *num)
em_queue_group_t	em_queue_group_next (void)
em_queue_t	em_queue_group_queue_first (unsigned int *num, em_queue_group_t queue_group)
em_queue_t	em_queue_group_queue_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.

Macro Definition Documentation

em_queue_group_get_first

#define em_queue_group_get_first   em_queue_group_first

Definition at line 329 of file event_machine_queue_group.h.

em_queue_group_get_mask

#define em_queue_group_get_mask   em_queue_group_mask

Definition at line 273 of file event_machine_queue_group.h.

em_queue_group_get_name

#define em_queue_group_get_name   em_queue_group_name

Definition at line 295 of file event_machine_queue_group.h.

em_queue_group_get_next

#define em_queue_group_get_next   em_queue_group_next

Definition at line 343 of file event_machine_queue_group.h.

em_queue_group_queue_get_first

#define em_queue_group_queue_get_first   em_queue_group_queue_first

Definition at line 385 of file event_machine_queue_group.h.

em_queue_group_queue_get_next

#define em_queue_group_queue_get_next   em_queue_group_queue_next

Definition at line 401 of file event_machine_queue_group.h.

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_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_core_mask.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 65 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

cli_top.c, dyn_cores.c, scheduling_latency.c, and timer_test_periodic.c.

Definition at line 90 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 reuse. 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

cli_top.c, dyn_cores.c, and queue_group.c.

Definition at line 106 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

Examples

dyn_cores.c.

Definition at line 136 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 212 of file event_machine_queue_group.c.

em_queue_group_first()

em_queue_group_t em_queue_group_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_next() after this call until it returns EM_QUEUE_GROUP_UNDEF. A new call to em_queue_group_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_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_first(&num);
while (qg != EM_QUEUE_GROUP_UNDEF) {
   qg = em_queue_group_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_next()

Definition at line 307 of file event_machine_queue_group.c.

em_queue_group_mask()

em_status_t em_queue_group_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 235 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_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_core_mask.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_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

Examples

dyn_cores.c.

Definition at line 189 of file event_machine_queue_group.c.

em_queue_group_name()

size_t em_queue_group_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 263 of file event_machine_queue_group.c.

em_queue_group_next()

em_queue_group_t em_queue_group_next

(

void

)

Continues the queue group iteration started by em_queue_group_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_first()

Definition at line 336 of file event_machine_queue_group.c.

em_queue_group_queue_first()

em_queue_t em_queue_group_queue_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_next() after this call until it returns EM_QUEUE_UNDEF. A new call to em_queue_group_queue_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_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_first(&num, queue_group);
while (q != EM_QUEUE_UNDEF) {
   q = em_queue_group_queue_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_next()

Definition at line 361 of file event_machine_queue_group.c.

em_queue_group_queue_next()

em_queue_t em_queue_group_queue_next

(

void

)

Return the queue group's next queue handle.

Continues the queue iteration started by em_queue_group_queue_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_first()

Definition at line 411 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 435 of file event_machine_queue_group.c.