Atomic group

Macros
#define	em_atomic_group_get_name   em_atomic_group_name
#define	em_atomic_group_get_first   em_atomic_group_first
#define	em_atomic_group_get_next   em_atomic_group_next
#define	em_atomic_group_queue_get_first   em_atomic_group_queue_first
#define	em_atomic_group_queue_get_next   em_atomic_group_queue_next

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)
size_t	em_atomic_group_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_first (unsigned int *num)
em_atomic_group_t	em_atomic_group_next (void)
em_queue_t	em_atomic_group_queue_first (unsigned int *num, em_atomic_group_t atomic_group)
em_queue_t	em_atomic_group_queue_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().

Macro Definition Documentation

em_atomic_group_get_first

#define em_atomic_group_get_first   em_atomic_group_first

Definition at line 220 of file event_machine_atomic_group.h.

em_atomic_group_get_name

#define em_atomic_group_get_name   em_atomic_group_name

Definition at line 173 of file event_machine_atomic_group.h.

em_atomic_group_get_next

#define em_atomic_group_get_next   em_atomic_group_next

Definition at line 236 of file event_machine_atomic_group.h.

em_atomic_group_queue_get_first

#define em_atomic_group_queue_get_first   em_atomic_group_queue_first

Definition at line 278 of file event_machine_atomic_group.h.

em_atomic_group_queue_get_next

#define em_atomic_group_queue_get_next   em_atomic_group_queue_next

Definition at line 294 of file event_machine_atomic_group.h.

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

event_types.c, loop_united.c, queue_types_ag.c, queue_types_local.c, and timer_test_periodic.c.

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

event_types.c, loop_united.c, queue_types_ag.c, queue_types_local.c, and timer_test_periodic.c.

Definition at line 214 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 397 of file event_machine_atomic_group.c.

em_atomic_group_first()

em_atomic_group_t em_atomic_group_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_next() after this call until it returns EM_ATOMIC_GROUP_UNDEF. A new call to em_atomic_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 atomic groups (output arg 'num') may not match the amount of atomic groups actually returned by iterating using em_atomic_group_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_first(&num);
while (ag != EM_ATOMIC_GROUP_UNDEF) {
   ag = em_atomic_group_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_next()

Examples

queue_types_ag.c.

Definition at line 413 of file event_machine_atomic_group.c.

em_atomic_group_name()

size_t em_atomic_group_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 364 of file event_machine_atomic_group.c.

em_atomic_group_next()

em_atomic_group_t em_atomic_group_next

(

void

)

Return the next atomic group handle.

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

Examples

queue_types_ag.c.

Definition at line 441 of file event_machine_atomic_group.c.

em_atomic_group_queue_first()

em_queue_t em_atomic_group_queue_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_next() after this call until it returns EM_QUEUE_UNDEF. A new call to em_atomic_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 atomic group (output arg 'num') may not match the amount of queues actually returned by iterating using em_atomic_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_atomic_group_queue_first(&num, atomic_group);
while (q != EM_QUEUE_UNDEF) {
   q = em_atomic_group_queue_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_next()

Examples

queue_types_ag.c.

Definition at line 463 of file event_machine_atomic_group.c.

em_atomic_group_queue_next()

em_queue_t em_atomic_group_queue_next

(

void

)

Return the atomic group's next queue handle.

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

Examples

queue_types_ag.c.

Definition at line 517 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 542 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

event_types.c, loop_united.c, queue_types_ag.c, queue_types_local.c, and timer_test_periodic.c.

Definition at line 257 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 number of static queues is provided by the user through 'queue.num_static' in em-odp.conf at runtime. A valid static queue handle can be derived as follows:

em_status_t status;
em_queue_t static_queue = em_queue_static_handle(x);
status = em_queue_create_static_ag(NULL, EM_QUEUE_PRIO_NORMAL,
                              atomic_group, static_queue, conf);

The 'x' in above pseudocode must be in range 0 to 'queue.num_static' - 1.

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 309 of file event_machine_atomic_group.c.