EM-core related

Enumerations
enum	em_core_type_t {   EM_CORE_TYPE_UNDEF = 0 , EM_CORE_TYPE_WORKER , EM_CORE_TYPE_CONTROL , EM_CORE_TYPE_EXTERNAL ,   EM_CORE_TYPE_LAST }

Functions
int	em_core_id (void)
uint32_t	em_core_count (void)
uint32_t	em_core_count_max (void)
uint32_t	em_core_type_count (em_core_type_t core_type)
int	em_core_id_first (em_core_type_t core_type, uint32_t *num)
int	em_core_id_next (void)
uint32_t	em_core_ids_available (em_core_type_t core_type, em_core_mask_t *core_mask)
em_core_type_t	em_core_type (void)

Detailed Description

core (thread) specific APIs.

An EM-core is a thread/process initialized through EM init APIs with the core type EM_CORE_TYPE_WORKER or EM_CORE_TYPE_CONTROL and is running the EM dispatch loop.

The Event Machine enumerates EM-cores within an EM instance as integers starting from 0. When adding an EM-core by calling em_init_local() on a new thread, the next lowest available integer (>=0) will be assigned to the EM-core as an id. Removing an EM-core from the instance frees the id and can leave a potential gap in the id range. This means that the core id range might not be coutiguous after a removal/termination of an EM-core. The next EM-core added will again acquire the first available core id and potentially fill a gap in the EM-core id range.

Enumeration Type Documentation

em_core_type_t

enum em_core_type_t

EM core type

Enumerator
EM_CORE_TYPE_UNDEF	Undef EM-core type
EM_CORE_TYPE_WORKER	Worker EM-core, has an EM-core ID and must call em_dispatch...(). An EM worker core is pinned to a single CPU by the user before calling em_init_local() and it runs the EM dispatch loop with no interrupts. Meant for real-time processing of events ("RT-core(s)").
EM_CORE_TYPE_CONTROL	Control EM-core, has an EM-core ID and calls dispatch (at least occasionally). An EM control core can e.g. function as a non-realtime EM-core that can participate in dispatching of events, but usually via carefully selected queues and queue groups to avoid disturbing the EM worker cores that can have real time workloads. An EM control core need not be pinned to single CPU, but still runs the dispatch loop. Meant for non-real-time processing ("NRT-core(s)").
EM_CORE_TYPE_EXTERNAL	External EM thread/process, no EM-core ID, no dispatching allowed. An EM external thread is not allowed to participate in event dispatching (i.e. it must not call any em_dispatch...() functions). An EM external thread can create/delete EM resources, send events and poll unscheduled queues etc. but is not considered an EM-core (hence no bit in an EM coremask) and cannot receive events via scheduled queues since dispatching is forbidden. Meant for external control or monitoring of EM.
EM_CORE_TYPE_LAST	Last, for bounds checking only

Definition at line 64 of file event_machine_core.h.

Function Documentation

em_core_count()

uint32_t em_core_count

(

void

)

The number of EM-cores currently running within the EM instance.

Adding an EM-core with em_init_local() increases the core count by one (1). Removing an EM-core with em_term_local() decreases the core count by one (1).

Only EM-cores of the type EM_CORE_TYPE_WORKER and EM_CORE_TYPE_CONTROL are included in the count.

Note that the EM-core count is not constant, instead it varies as EM-cores are added or removed. The current EM-core count is limited by em_conf_t::core_count that sets the maximum count for the EM instance.

Returns

The number of currently running EM-cores.

Examples

bench_event.c.

Definition at line 61 of file event_machine_core.c.

em_core_count_max()

uint32_t em_core_count_max

(

void

)

Maximum number of concurrently running EM-cores allowed for this EM instance.

The maximum number of EM-cores is a constant value set at startup and cannot be changed afterwards. The value is the same as the em_conf_t::core_count set by the user and passed to em_init() (if accepted by EM). The user provided maximum EM-core count value is within the range [1, EM_MAX_CORES].

See also

em_conf_t::core_count

The max number of EM-cores is concerned with concurrently running EM-cores of the type EM_CORE_TYPE_CONTROL or EM_CORE_TYPE_WORKER. Additionally the user may create threads/processes of type EM_CORE_TYPE_EXTERNAL that are not included in this max count, see em_core_type_t.

Returns

Maximum number of EM-cores supported by this EM instance.

Definition at line 66 of file event_machine_core.c.

em_core_id()

int em_core_id

(

void

)

Get the EM-core id of the current EM thread/process.

Returns the EM-core id (logical id) of the calling thread/process. The Event Machine enumerates EM-cores (i.e. threads/processes of type EM_CORE_TYPE_WORKER or EM_CORE_TYPE_CONTROL running the EM dispatch loop) within an EM instance as integers starting from 0. The core id range can contain gaps if EM-cores have been terminated/removed. Note that external threads/processes of type EM_CORE_TYPE_EXTERNAL do not have an EM-core id and this function will return -1 for those instead. The thread/process must have been initialized as an EM-core with em_init_local() (or the older em_init_core()) to have a valid EM-core id.

Note

The core id returned for an EM external thread/process of type EM_CORE_TYPE_EXTERNAL is -1 (i.e. no EM-core id available).

Returns

Current logical EM core id.

Return values

0	to EM_MAX_CORES-1 for EM_CORE_TYPE_WORKER or EM_CORE_TYPE_CONTROL
-1	for EM_CORE_TYPE_EXTERNAL
undefined	for threads/processes not initialized as EM-cores

Examples

api_hooks.c, atomic_processing_end.c, bench_event.c, bench_pool.c, cli_top.c, dispatcher_callback.c, dyn_cores.c, error.c, event_group.c, event_group_abort.c, event_group_assign_end.c, event_group_chaining.c, event_types.c, fractal.c, hello.c, loop_united.c, ordered.c, pool_perf.c, queue_group.c, queue_groups.c, queue_types_ag.c, queue_types_local.c, queues.c, queues_local.c, queues_output.c, queues_unscheduled.c, scheduling_latency.c, send_multi.c, timer_hello.c, timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 56 of file event_machine_core.c.

em_core_id_first()

int em_core_id_first	(	em_core_type_t	core_type,
		uint32_t *	num
	)

Initialize EM-core id iteration and get the first EM-core id.

Start a new iteration over EM-core ids and get the EM-core id of the first (=lowest id) EM-core available at the time of the call. Optionally outputs the current number of EM-cores via the 'num' output parameter. The iteration can be continued with em_core_id_next() until all EM-core ids have been returned. The iteration stops when either of the functions return -1.

Only EM-cores of the type EM_CORE_TYPE_WORKER and/or EM_CORE_TYPE_CONTROL are included in the iteration, as set by the 'core_type' parameter.

The EM-core id range may not be contiguous if EM-cores have been removed after startup. The iteration will return the available EM-core ids in ascending order. The iteration functions always represent a snapshot of the available core-ids at a certain time - if EM-cores are added or removed just after any of the calls then the returned ids might be not be up-to-date.

Example usage:

uint32_t num;
int core_id = em_core_id_first(EM_CORE_TYPE_WORKER, &num);
while (core_id >= 0) {
   ...
   core_id = em_core_id_next();
}

Parameters

	core_type	EM-core type to include in the iteration. The core type can be one of the following: EM_CORE_TYPE_WORKER: only include worker EM-cores EM_CORE_TYPE_CONTROL: only include control EM-cores EM_CORE_TYPE_UNDEF: include both worker and control EM-cores (special usage for the '_UNDEF' type here)
[out]	num	Optional output parameter to store the current number of EM-cores.

Note

the 'num' output parameter only represent the number of EM-cores at the time of the call and thus the number of iterations with em_core_id_next() until no more EM-cores are available may differ.

Returns

the first available EM-core id or -1 if no EM-cores exist

Return values

-1	if no EM-cores exist (of type worker or control)

See also

em_core_id_next()

Definition at line 97 of file event_machine_core.c.

em_core_id_next()

int em_core_id_next

(

void

)

Continue iteration over EM-core ids and get the next EM-core id available.

Continue the EM-core iteration started by em_core_id_first() and get the next EM-core id available at the time of the call. The iteration can be continued with successive calls to em_core_id_next() until all EM-core ids have been returned. The iteration stops when the function returns -1.

Only EM-cores of the type EM_CORE_TYPE_WORKER and/or EM_CORE_TYPE_CONTROL are included in the iteration, as set by the 'core_type' parameter in the em_core_id_first() call.

Note

This API function must only be used after first successfully calling em_core_id_first() to initialize the iteration.

Returns

the next available EM-core id or -1 if no more EM-cores exist

See also

em_core_id_first()

Definition at line 144 of file event_machine_core.c.

em_core_ids_available()

uint32_t em_core_ids_available	(	em_core_type_t	core_type,
		em_core_mask_t *	core_mask
	)

Retrieve the core mask for all available EM-cores of the specified core type.

This function populates the provided core mask with the currently running EM-cores that match the specified core type and returns the number of EM-cores of the given type set in the mask.

Parameters

core_type	The type of the EM-cores to include in the mask. The core type can be one of the following: EM_CORE_TYPE_WORKER: only include worker EM-cores EM_CORE_TYPE_CONTROL: only include control EM-cores EM_CORE_TYPE_UNDEF: include both worker and control EM-cores (special usage for the '_UNDEF' type here)
core_mask	Pointer to the core mask to be populated. The core mask is cleared before the EM-cores are set, thus also in error cases the mask will be zeroed (e.g. when an invalid 'core_type' is given).

Returns

the number of EM-cores of the specified type set in the mask

Return values

0	if no EM-cores of the given type available

Definition at line 166 of file event_machine_core.c.

em_core_type()

em_core_type_t em_core_type

(

void

)

EM-core type of the calling EM thread/process.

Return the EM-core type of the calling thread/process. The thread/process must have been initialized as an EM-core with em_init_local() (or the older em_init_core()) to have a valid EM-core type.

Returns

EM-core type.

Return values

undefined

for threads/processes not initialized as EM-cores

Examples

dyn_cores.c.

Definition at line 202 of file event_machine_core.c.

em_core_type_count()

uint32_t em_core_type_count

(

em_core_type_t

core_type

)

The number of EM-cores of the specified type currently running within the EM instance.

Similar to em_core_count(), but only counts EM-cores of the specified type.

Parameters

core_type

The type of the EM-cores to include in the count. The core type can be one of the following: EM_CORE_TYPE_WORKER: only include worker EM-cores EM_CORE_TYPE_CONTROL: only include control EM-cores EM_CORE_TYPE_UNDEF: include both worker and control EM-cores (special usage for the '_UNDEF' type here) EM_CORE_TYPE_EXTERNAL: only include EM external threads/processes (EM external threads/processes are not considered EM-cores since they do not have an EM-core id)

Note that the EM-core count is not constant, instead it varies as EM-cores are added or removed.

Returns

The number of currently running EM-cores.

Definition at line 71 of file event_machine_core.c.