Atomic group

Event Machine atomic queue group (new to API 1.1) More...

Functions
em_atomic_group_t	em_atomic_group_create (const char *name, em_queue_group_t queue_group)
em_status_t	em_atomic_group_delete (em_atomic_group_t atomic_group)
em_queue_t	em_queue_create_ag (const char *name, em_queue_prio_t prio, em_atomic_group_t atomic_group, const em_queue_conf_t *conf)
em_status_t	em_queue_create_static_ag (const char *name, em_queue_prio_t prio, em_atomic_group_t atomic_group, em_queue_t queue, const em_queue_conf_t *conf)
em_atomic_group_t	em_atomic_group_get (em_queue_t queue)
size_t	em_atomic_group_get_name (em_atomic_group_t atomic_group, char *name, size_t maxlen)
em_atomic_group_t	em_atomic_group_find (const char *name)
em_atomic_group_t	em_atomic_group_get_first (unsigned int *num)
em_atomic_group_t	em_atomic_group_get_next (void)
em_queue_t	em_atomic_group_queue_get_first (unsigned int *num, em_atomic_group_t atomic_group)
em_queue_t	em_atomic_group_queue_get_next (void)
uint64_t	em_atomic_group_to_u64 (em_atomic_group_t atomic_group)

Detailed Description

Event Machine atomic queue group (new to API 1.1)

An atomic group combines multiple atomic queues in such a way that only one event from any of the included queues can be scheduled to the application at any one time, effectively scheduling several queues like a single atomic one. The main use case is to provide a protected race free context by atomic scheduling but allow multiple priorities (all of the queue contexts for queues in one atomic group are protected. The related EO context is also protected, if all queues of that EO are in one atomic group only, thus effectively creating an atomic EO).

All queues in an atomic group belong to the same queue group given when creating a new atomic group. Queues for an atomic group must be created using _ag - functions, but can be deleted normally using em_queue_delete().

Function Documentation

em_atomic_group_create()

em_atomic_group_t em_atomic_group_create	(	const char *	name,
		em_queue_group_t	queue_group
	)

Create a new atomic group

Some systems may have a limited number of atomic groups available or a limited number of queues per atomic group.

The given name string is copied into an EM internal data structure. The maximum string length is EM_ATOMIC_GROUP_NAME_LEN. Duplicate names are allowed, but find will only match one of them.

Parameters

name	Atomic group name (optional, NULL ok)
queue_group	Existing queue group to use for this atomic group

Returns

Atomic group or EM_ATOMIC_GROUP_UNDEF on error.

Examples

queue_types_ag.c, queue_types_local.c, and timer_test_periodic.c.

Definition at line 40 of file event_machine_atomic_group.c.

em_atomic_group_delete()

em_status_t em_atomic_group_delete

(

em_atomic_group_t

atomic_group

)

Delete an atomic group.

Attention

An atomic group can only be deleted after all queues belonging to it have been removed from the EOs and deleted.

Parameters

atomic_group

Atomic group to delete

Returns

EM_OK if successful.

See also

em_atomic_group_create()

Examples

queue_types_ag.c, queue_types_local.c, and timer_test_periodic.c.

Definition at line 181 of file event_machine_atomic_group.c.

em_atomic_group_find()

em_atomic_group_t em_atomic_group_find

(

const char *

name

)

Find atomic group by name.

Finds an atomic 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	the name to look for

Returns

atomic group or EM_ATOMIC_GROUP_UNDEF if not found.

Examples

queue_types_ag.c.

Definition at line 367 of file event_machine_atomic_group.c.

em_atomic_group_get()

em_atomic_group_t em_atomic_group_get

(

em_queue_t

queue

)

Get the associated atomic group of the given queue.

Returns the atomic group of the given queue.

Parameters

queue

Queue for the query

Returns

Queue specific atomic group or EM_ATOMIC_GROUP_UNDEF if the given queue is not valid or belong to an atomic group.

See also

em_atomic_group_create()

Definition at line 316 of file event_machine_atomic_group.c.

em_atomic_group_get_first()

em_atomic_group_t em_atomic_group_get_first

(

unsigned int *

num

)

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

Can be used to initialize the iteration to retrieve all created atomic groups for debugging or management purposes. Use em_atomic_group_get_next() after this call until it returns EM_ATOMIC_GROUP_UNDEF. A new call to em_atomic_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 atomic groups (output arg 'num') may not match the amount of atomic groups actually returned by iterating using em_atomic_group_get_next() if atomic groups are added or removed in parallel by another core. The order of the returned atomic group handles is undefined.

unsigned int num;
em_atomic_group_t ag = em_atomic_group_get_first(&num);
while (ag != EM_ATOMIC_GROUP_UNDEF) {
   ag = em_atomic_group_get_next();
}

Parameters

[out]

num

Pointer to an unsigned int to store the amount of atomic groups into

Returns

The first atomic group handle or EM_ATOMIC_GROUP_UNDEF if none exist

See also

em_atomic_group_get_next()

Examples

queue_types_ag.c.

Definition at line 384 of file event_machine_atomic_group.c.

em_atomic_group_get_name()

size_t em_atomic_group_get_name	(	em_atomic_group_t	atomic_group,
		char *	name,
		size_t	maxlen
	)

Get the name of an atomic 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.

If the atomic group has no name, the function returns 0 and writes an empty string.

Parameters

	atomic_group	Atomic group
[out]	name	Destination buffer
	maxlen	Maximum length (including the terminating '0')

Returns

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

Examples

queue_types_ag.c, and queue_types_local.c.

Definition at line 334 of file event_machine_atomic_group.c.

em_atomic_group_get_next()

em_atomic_group_t em_atomic_group_get_next

(

void

)

Return the next atomic group handle.

Continues the atomic group iteration started by em_atomic_group_get_first() and returns the next atomic group handle.

Returns

The next atomic group handle or EM_ATOMIC_GROUP_UNDEF if the atomic group iteration is completed (i.e. no more atomic groups available).

See also

em_atomic_group_get_first()

Examples

queue_types_ag.c.

Definition at line 413 of file event_machine_atomic_group.c.

em_atomic_group_queue_get_first()

em_queue_t em_atomic_group_queue_get_first	(	unsigned int *	num,
		em_atomic_group_t	atomic_group
	)

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

Can be used to initialize the iteration to retrieve all queues associated with the given atomic group for debugging or management purposes. Use em_atomic_group_queue_get_next() after this call until it returns EM_QUEUE_UNDEF. A new call to em_atomic_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 atomic group (output arg 'num') may not match the amount of queues actually returned by iterating using em_atomic_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_atomic_group_queue_get_first(&num, atomic_group);
while (q != EM_QUEUE_UNDEF) {
   q = em_atomic_group_queue_get_next();
}

Parameters

[out]	num	Pointer to unsigned int to store the amount of queues into.
	atomic_group	Atomic group handle

Returns

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

See also

em_atomic_group_queue_get_next()

Examples

queue_types_ag.c.

Definition at line 436 of file event_machine_atomic_group.c.

em_atomic_group_queue_get_next()

em_queue_t em_atomic_group_queue_get_next

(

void

)

Return the atomic group's next queue handle.

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

Returns

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

See also

em_atomic_group_queue_get_first()

Examples

queue_types_ag.c.

Definition at line 492 of file event_machine_atomic_group.c.

em_atomic_group_to_u64()

uint64_t em_atomic_group_to_u64

(

em_atomic_group_t

atomic_group

)

Convert an atomic group handle to an unsigned integer

Parameters

atomic_group

atomic 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_atomic_group_t handle.

Definition at line 517 of file event_machine_atomic_group.c.

em_queue_create_ag()

em_queue_t em_queue_create_ag	(	const char *	name,
		em_queue_prio_t	prio,
		em_atomic_group_t	atomic_group,
		const em_queue_conf_t *	conf
	)

Create a new queue with a dynamic queue handle belonging to an atomic group.

Queues created with this are always of type EM_QUEUE_TYPE_ATOMIC.

The given name string is copied to EM internal data structure. The maximum string length is EM_QUEUE_NAME_LEN.

The 'conf' argument is optional and can be used to pass extra attributes (e.g. require non-blocking behaviour, if supported) to the system specific implementation.

Parameters

name	Queue name (optional, NULL ok)
prio	Queue priority
atomic_group	Existing atomic group for this queue
conf	Optional configuration data, NULL for defaults

Returns

New queue handle or EM_QUEUE_UNDEF on an error.

See also

em_atomic_group_create(), em_queue_delete(), em_queue_create()

Examples

queue_types_ag.c, queue_types_local.c, and timer_test_periodic.c.

Definition at line 224 of file event_machine_atomic_group.c.

em_queue_create_static_ag()

em_status_t em_queue_create_static_ag	(	const char *	name,
		em_queue_prio_t	prio,
		em_atomic_group_t	atomic_group,
		em_queue_t	queue,
		const em_queue_conf_t *	conf
	)

Create a new queue with a static queue handle belonging to an atomic group.

Otherwise equivalent to em_queue_create_ag().

Note, that the system may have a limited amount of static handles available, so prefer the use of dynamic queues, unless static handles are really needed. The range of static identifiers/handles is system dependent, but macros EM_QUEUE_STATIC_MIN and EM_QUEUE_STATIC_MAX can be used to abstract actual values, e.g. use EM_QUEUE_STATIC_MIN+x for the application.

Parameters

name	Queue name (optional, NULL ok)
prio	Queue priority
atomic_group	Existing atomic group for this queue
queue	Requested queue handle from the static range
conf	Optional configuration data, NULL for defaults

Returns

EM_OK if successful.

See also

em_queue_create_ag(), em_atomic_group_create(), em_queue_delete()

Definition at line 269 of file event_machine_atomic_group.c.