event_machine_config.h File Reference

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	EM_STATIC_CAST(type, value)   ((type)(value))
#define	EM_REINTERPRET_CAST(type, value)   ((type)(value))
#define	EM_MAX_CORES   64
#define	EM_MAX_EXTTHRS   32
#define	EM_MAX_ATOMIC_GROUPS   128
#define	EM_ATOMIC_GROUP_NAME_LEN   32
#define	EM_MAX_EOS   512
#define	EM_EO_NAME_LEN   32
#define	EM_MAX_EVENT_GROUPS   1024
#define	EM_EVENT_GROUP_MAX_NOTIF   6
#define	EM_QUEUE_NAME_LEN   32
#define	EM_MAX_OUTPUT_QUEUES   64
#define	EM_QUEUE_PRIO_NUM   8
#define	EM_QUEUE_RANGE_OFFSET   1
#define	EM_QUEUE_MAX_AGGR   4
#define	EM_MAX_QUEUE_GROUPS   (EM_MAX_CORES + 64)
#define	EM_QUEUE_GROUP_DEFAULT   EM_REINTERPRET_CAST(em_queue_group_t, EM_MAX_QUEUE_GROUPS)
#define	EM_QUEUE_GROUP_NAME_LEN   32
#define	EM_QUEUE_GROUP_DEFAULT_NAME   "default"
#define	EM_QUEUE_GROUP_CORE_BASE_NAME   "core"
#define	EM_CONFIG_POOLS   16
#define	EM_POOL_DEFAULT   EM_REINTERPRET_CAST(em_pool_t, 1)
#define	EM_POOL_NAME_LEN   32
#define	EM_MAX_SUBPOOLS   4
	The maximum number of subpools in each EM pool. The subpool is a pool with buffers of only one size.
#define	EM_POOL_DEFAULT_NAME   "default"
#define	EM_POOL_SUBPOOL_STAT_INTERNAL   129
#define	EM_EVENT_USER_AREA_MAX_SIZE   256
#define	EM_SCHED_MULTI_MAX_BURST   32
#define	EM_SCHED_AG_MULTI_MAX_BURST   32
#define	EM_QUEUE_LOCAL_MULTI_MAX_BURST   32
#define	EM_EO_MULTIRCV_MAX_EVENTS   32
#define	EM_CALLBACKS_MAX   8
#define	EM_OUTPUT_QUEUE_IMMEDIATE   0
#define	EM_DISPATCH_CALLBACKS_ENABLE   1
#define	EM_API_HOOKS_ENABLE   1
#define	EM_EVENT_GROUP_SAFE_MODE   1
#define	EM_IDLE_HOOKS_ENABLE   1
#define	EM_SCHED_WAIT_ENABLE   1
#define	EM_CHECK_LEVEL   3
#define	EM_ESV_ENABLE   1
#define	EM_DEBUG_PRINT_ALL   0
#define	EM_DEBUG_PRINT_TIMER   0
#define	EM_DEBUG_PRINT_BASE   0
#define	EM_DEBUG_TIMESTAMP_ENABLE   0

Detailed Description

Event Machine configuration options

Definition in file event_machine_config.h.

Macro Definition Documentation

EM_API_HOOKS_ENABLE

#define EM_API_HOOKS_ENABLE   1

Enable the usage of EM API hooks

User provided API hook functions can be provided via em_init(). EM will call the given hooks each time the corresponding API function is called.

Definition at line 374 of file event_machine_config.h.

EM_ATOMIC_GROUP_NAME_LEN

#define EM_ATOMIC_GROUP_NAME_LEN   32

Max atomic group name length

Examples

loop_united.c, queue_types_ag.c, and queue_types_local.c.

Definition at line 119 of file event_machine_config.h.

EM_CALLBACKS_MAX

#define EM_CALLBACKS_MAX   8

Maximum number of EM callbacks/hooks that can be registered.

The user may register up to the number 'EM_CALLBACKS_MAX' of each callback/hook. API-hooks, such as the alloc-, free- and send-hook, or dispatcher callbacks, such as the enter- and exit-callbacks as well as idle-hooks can be registered each up to this limit.

Definition at line 344 of file event_machine_config.h.

EM_CHECK_LEVEL

#define EM_CHECK_LEVEL   3

EM Error check level

Conditionally compiled error checking level, range 0...3 Level 0 does not do any runtime argument checking (be careful!) Level 1 adds minimum checks Level 2 adds most checks except the slowest ones Level 3 adds all checks and gives lowest performance

Note

em-odp: the 'EM_CHECK_LEVEL' value is set/changed by a command-line option to the 'configure' script, e.g.: $build> ../configure ... –enable-check-level=3

Definition at line 437 of file event_machine_config.h.

EM_CONFIG_POOLS

#define EM_CONFIG_POOLS   16

Maximum number of EM pools

Definition at line 256 of file event_machine_config.h.

EM_DEBUG_PRINT_ALL

#define EM_DEBUG_PRINT_ALL   0

EM debug printouts - enable/disable all debug printouts

'0': disabled '1': enabled

The EM_DEBUG_PRINT_ALL define is a convenience define that, if set via 'configure –enable-debug-print/-all', will set all individual debug print options to 'enabled' (1). Summary of configure interactions: Default: EM_DEBUG_PRINT_ALL = 0, Subflags: EM_DEBUG_PRINT_TIMER = 0, EM_DEBUG_PRINT_BASE = 0 –enable-debug-print-all (alias: –enable-debug-print): _ALL=1 seeds _TIMER=1 & _BASE=1 (unless individually disabled). –disable-debug-print-all: _ALL=0, subflags keep explicitly set values, otherwise they are set to 0. –enable-debug-print-timer/base: set that subflag to 1 (_ALL unchanged). –disable-debug-print-timer/base: set that subflag to 0 and force _ALL=0. Disabling any subflag after enabling _ALL clears _ALL (non-uniform state).

Definition at line 482 of file event_machine_config.h.

EM_DEBUG_PRINT_BASE

#define EM_DEBUG_PRINT_BASE   0

EM debug printouts - enable/disable base level debug printouts

'0': disabled '1': enabled

The 'EM_DEBUG_PRINT_BASE' value is set/changed by a command-line option to the 'configure' script, e.g.: $build> ../configure ... –enable-debug-print-base[=yes|no]

Note: seeded to 1 by –enable-debug-print/-all unless overridden.

Definition at line 514 of file event_machine_config.h.

EM_DEBUG_PRINT_TIMER

#define EM_DEBUG_PRINT_TIMER   0

EM debug printouts - enable/disable timer debug printouts

'0': disabled '1': enabled

The 'EM_DEBUG_PRINT_TIMER' value is set/changed by a command-line option to the 'configure' script, e.g.: $build> ../configure ... –enable-debug-print-timer[=yes|no]

Note: seeded to 1 by –enable-debug-print/-all unless overridden.

Definition at line 498 of file event_machine_config.h.

EM_DEBUG_TIMESTAMP_ENABLE

#define EM_DEBUG_TIMESTAMP_ENABLE   0

Debug Timestamps for timing analysis.

Enabling may reduce performance but allows to trace dispatcher timings. Timestamps are per dispatcher (thread local).

'0': disabled (default) '1': enabled, lower overhead but potentially inaccurate (no HW barriers) '2': enabled, strict version with full HW barriers

Use value 1 for lower overhead timestamps and value 2 for strict timestamp with HW barriers.

The 'EM_DEBUG_TIMESTAMP_ENABLE' value is set/changed by a command-line option to the 'configure' script, e.g.: $build> ../configure ... –enable-debug-timestamps=0...2

See also

event_machine_helper.h

Definition at line 537 of file event_machine_config.h.

EM_DISPATCH_CALLBACKS_ENABLE

#define EM_DISPATCH_CALLBACKS_ENABLE   1

Definition at line 364 of file event_machine_config.h.

EM_EO_MULTIRCV_MAX_EVENTS

#define EM_EO_MULTIRCV_MAX_EVENTS   32

The default maximum number of events passed to the EO's multi-event receive function (when the EO has been created with em_eo_create_multircv()). This value is used by EM as a default if the user does not specify a value (i.e. gives '0') for 'em_eo_multircv_param_t::max_events' when calling em_eo_create_multircv()

Examples

event_types.c.

Definition at line 332 of file event_machine_config.h.

EM_EO_NAME_LEN

#define EM_EO_NAME_LEN   32

Maximum EO name string length

Examples

atomic_processing_end.c, dyn_cores.c, event_types.c, and queue_types_ag.c.

Definition at line 133 of file event_machine_config.h.

EM_ESV_ENABLE

#define EM_ESV_ENABLE   1

Event State Verification (ESV)

'0': disabled '1': enabled - event state is verified when the event is passed from EM to the user (e.g. dispatch) and from the user to EM (e.g. send) to catch illegal usage patterns like double-send, double-free, usage-after-send etc.

Also see the config/em-odp.conf file for ESV runtime options!

Note

em-odp: the 'EM_ESV_ENABLE' value is set/changed by a command-line option to the 'configure' script, e.g.: $build> ../configure ... –enable-esv[=yes|no]

Definition at line 456 of file event_machine_config.h.

EM_EVENT_GROUP_MAX_NOTIF

#define EM_EVENT_GROUP_MAX_NOTIF   6

Maximum number of notifications

Definition at line 147 of file event_machine_config.h.

EM_EVENT_GROUP_SAFE_MODE

#define EM_EVENT_GROUP_SAFE_MODE   1

Guards event groups in undefined and error situations

Excess and aborted group events don't belong to a valid group when received. Most event group APIs check if the core local event group has expired during receive function. Impacts performance when event groups are used.

Examples

event_group_abort.c.

Definition at line 385 of file event_machine_config.h.

EM_EVENT_USER_AREA_MAX_SIZE

#define EM_EVENT_USER_AREA_MAX_SIZE   256

The maximum size in bytes that can be configured for the event user area. The user area is located outside of the payload in the event metadata (hdr) and can be used to store event related state without affecting the payload.

Definition at line 295 of file event_machine_config.h.

EM_IDLE_HOOKS_ENABLE

#define EM_IDLE_HOOKS_ENABLE   1

Enable the usage of EM idle hooks

User provided idle hook functions can be provided via em_conf_t::idle_hooks when calling em_init() or via their register functions. EM will call the given hooks in the dispatcher depending on whether there are events to be processed by the core.

Note

em-odp: the 'EM_IDLE_HOOKS_ENABLE' value is set/changed by a command-line option to the 'configure' script, e.g.: $build> ../configure ... –enable-idle-hooks[=yes|no]

Definition at line 401 of file event_machine_config.h.

EM_MAX_ATOMIC_GROUPS

#define EM_MAX_ATOMIC_GROUPS   128

Maximum number of EM atomic groups

Definition at line 112 of file event_machine_config.h.

EM_MAX_CORES

#define EM_MAX_CORES   64

Compile-time upper limit for the maximum number of EM-cores.

Sets the maximum number of EM-cores that can be requested to be supported by EM at startup, i.e. sets a limit for the em_conf_t::core_count parameter. This is a compile time upper limit for the number of EM-cores of type EM_CORE_TYPE_WORKER or EM_CORE_TYPE_CONTROL.

Examples

cli_top.c.

Definition at line 97 of file event_machine_config.h.

EM_MAX_EOS

#define EM_MAX_EOS   512

Maximum total number of EOs

Definition at line 126 of file event_machine_config.h.

EM_MAX_EVENT_GROUPS

#define EM_MAX_EVENT_GROUPS   1024

Maximum number of event groups

Definition at line 140 of file event_machine_config.h.

EM_MAX_EXTTHRS

#define EM_MAX_EXTTHRS   32

Max number of EM external threads/processes supported, i.e. EM external threads/processes of type EM_CORE_TYPE_EXTERNAL.

Definition at line 105 of file event_machine_config.h.

EM_MAX_OUTPUT_QUEUES

#define EM_MAX_OUTPUT_QUEUES   64

Maximum number of output queues

Examples

queues_output.c.

Definition at line 161 of file event_machine_config.h.

EM_MAX_QUEUE_GROUPS

#define EM_MAX_QUEUE_GROUPS   (EM_MAX_CORES + 64)

Maximum number of EM queue groups

Examples

cli_top.c, and queue_groups.c.

Definition at line 206 of file event_machine_config.h.

EM_MAX_SUBPOOLS

#define EM_MAX_SUBPOOLS   4

The maximum number of subpools in each EM pool. The subpool is a pool with buffers of only one size.

Examples

bench_pool.c.

Definition at line 276 of file event_machine_config.h.

EM_OUTPUT_QUEUE_IMMEDIATE

#define EM_OUTPUT_QUEUE_IMMEDIATE   0

'0': allow EM to buffer events sent to output queues before calling the user provided output callback to improve throughput '1': each em_send/_multi() will immediately call the user provided output queue callback with no EM internal buffering This define mostly affects behaviour and performance when sending events from an ordered scheduling context where EM needs to ensure event ordering before calling the user provided output callback function.

Definition at line 357 of file event_machine_config.h.

EM_POOL_DEFAULT

#define EM_POOL_DEFAULT   EM_REINTERPRET_CAST(em_pool_t, 1)

Define the EM default event pool

Examples

api_hooks.c, atomic_processing_end.c, cli_top.c, dispatcher_callback.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_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 262 of file event_machine_config.h.

EM_POOL_DEFAULT_NAME

#define EM_POOL_DEFAULT_NAME   "default"

The name of the EM default event pool

Definition at line 282 of file event_machine_config.h.

EM_POOL_NAME_LEN

#define EM_POOL_NAME_LEN   32

Max event pool name length

Examples

hello.c.

Definition at line 268 of file event_machine_config.h.

EM_POOL_SUBPOOL_STAT_INTERNAL

#define EM_POOL_SUBPOOL_STAT_INTERNAL   129

Reserve for EM pool subpool statistic internal use

Definition at line 287 of file event_machine_config.h.

EM_QUEUE_GROUP_CORE_BASE_NAME

#define EM_QUEUE_GROUP_CORE_BASE_NAME   "core"

Base-name of EM core-specific queue groups (one per EM-core), if created by EM (note: see the EM runtime config file for option). The full queue group name for a single-core group is: "core" + "%d", which gives "core0", "core1", ... "core99", ... EM earlier relied on these queue groups for internal core specific messaging and also allowed applications to use them. Currently EM does not internally need these groups but will create them based on an EM config file option for applications relying on their existence.

Example: Find the queue group that includes only this core. (EM single-core queue group creation enabled in config file)

char qgrp_name[EM_QUEUE_GROUP_NAME_LEN];
int core = em_core_id();
em_queue_group_t qgrp_core;
 
snprintf(qgrp_name, sizeof(qgrp_name), "%s%d",
    EM_QUEUE_GROUP_CORE_BASE_NAME, core);
...
qgrp_core = em_queue_group_find(qgrp_name);
...

Definition at line 250 of file event_machine_config.h.

EM_QUEUE_GROUP_DEFAULT

#define EM_QUEUE_GROUP_DEFAULT   EM_REINTERPRET_CAST(em_queue_group_t, EM_MAX_QUEUE_GROUPS)

Default queue group for EM

Examples

api_hooks.c, atomic_processing_end.c, bench_event.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 212 of file event_machine_config.h.

EM_QUEUE_GROUP_DEFAULT_NAME

#define EM_QUEUE_GROUP_DEFAULT_NAME   "default"

The name of the EM default queue group

Definition at line 224 of file event_machine_config.h.

EM_QUEUE_GROUP_NAME_LEN

#define EM_QUEUE_GROUP_NAME_LEN   32

Max queue group name length

Examples

dyn_cores.c, and queue_groups.c.

Definition at line 218 of file event_machine_config.h.

EM_QUEUE_LOCAL_MULTI_MAX_BURST

#define EM_QUEUE_LOCAL_MULTI_MAX_BURST   32

The maximum number of events from a local queue (EM_QUEUE_TYPE_LOCAL) to dispatch in one burst.

Definition at line 321 of file event_machine_config.h.

EM_QUEUE_MAX_AGGR

#define EM_QUEUE_MAX_AGGR   4

The maximum number of aggregator queues that can be created for a single EM queue. An aggregator queue allows multiple events to be aggregated into a vector event before enqueueing to the parent queue.

See also

em_queue_aggr_conf_t and em_queue_param_t.

Note

The actual maximum number of aggregator queues that can be created for a single EM queue is determined by the minimum of this value and the ODP implementation limits for event aggregators, which can be queried with odp_queue_capability() for plain queues or with odp_schedule_capability() for scheduled queues, and are checked by EM at queue creation time.

Definition at line 199 of file event_machine_config.h.

EM_QUEUE_NAME_LEN

#define EM_QUEUE_NAME_LEN   32

Maximum queue name string length

Examples

atomic_processing_end.c, dyn_cores.c, queue_types_ag.c, and queues_output.c.

Definition at line 154 of file event_machine_config.h.

EM_QUEUE_PRIO_NUM

#define EM_QUEUE_PRIO_NUM   8

Number of queue scheduling priorities, normal default is 8.

See also

em_queue_prio_e

Definition at line 169 of file event_machine_config.h.

EM_QUEUE_RANGE_OFFSET

#define EM_QUEUE_RANGE_OFFSET   1

Determines the EM queue handles range to use. Note: value must be >= 1 and <= 'UINT16_MAX - em_queue_max_num() + 1' idx EM Queue handle 0 -> 0 + offset 1 -> 1 + offset ... max-1 -> max-1 + offset

Definition at line 182 of file event_machine_config.h.

EM_REINTERPRET_CAST

#define EM_REINTERPRET_CAST	(		type,
			value
	)		((type)(value))

Support C++ reinterpret casts in EM API files

Definition at line 83 of file event_machine_config.h.

EM_SCHED_AG_MULTI_MAX_BURST

#define EM_SCHED_AG_MULTI_MAX_BURST   32

The maximum number of events from an atomic group to dispatch in one burst.

Definition at line 313 of file event_machine_config.h.

EM_SCHED_MULTI_MAX_BURST

#define EM_SCHED_MULTI_MAX_BURST   32

The maximum number of events to request from the scheduler and then dispatch in one burst.

Note

the odp sched burst size is determined by the odp-config-file values: sched_basic: burst_size_default[...] and burst_size_max[...]

Definition at line 306 of file event_machine_config.h.

EM_SCHED_WAIT_ENABLE

#define EM_SCHED_WAIT_ENABLE   1

Enable the EM dispatcher/scheduler to set the time (in ns) the scheduler should wait for events before returning (when no events are immediately available). Waiting for events, rather than busy-waiting, might save power. The EM dispatch loop will call odp_schedule_multi(..., sched_wait_ns, ...) when EM_SCHED_WAIT_ENABLE=1. The EM dispatch loop will call odp_schedule_multi_no_wait() when EM_SCHED_WAIT_ENABLE=0. The 'sched_wait_ns' value can be set via an EM config file option: config/em-odp.conf: dispatch.sched_wait_ns = value

Note

em-odp: the 'EM_SCHED_WAIT_ENABLE' value is set/changed by a command-line option to the 'configure' script, e.g.: $build> ../configure ... –enable-sched-wait[=yes|no]

Definition at line 420 of file event_machine_config.h.

EM_STATIC_CAST

#define EM_STATIC_CAST	(		type,
			value
	)		((type)(value))

Support C++ static casts in EM API files

Definition at line 74 of file event_machine_config.h.