Data Structures
struct	em_conf_t

struct	em_conf_local_t

struct	em_term_local_t

struct	em_startup_pool_conf_t

struct	em_cfgfile_opts_t

Typedefs
typedef int(*	em_input_poll_func_t) (void)

typedef int(*	em_output_drain_func_t) (void)

Functions
void	em_conf_init (em_conf_t *conf)

em_status_t	em_init (const em_conf_t *conf)

em_status_t	em_conf_opts (em_conf_t *conf_opts)

void	em_conf_opts_print (void)

void	em_conf_local_init (em_conf_local_t *conf_local)

em_status_t	em_init_local (const em_conf_local_t *conf_local)

em_status_t	em_conf_local_opts (em_conf_local_t *conf_local_opts)

void	em_conf_local_opts_print (void)

em_status_t	em_init_core (void)

void	em_term_local_init (em_term_local_t *term_local)

em_status_t	em_term_local (const em_term_local_t *term_local)

em_status_t	em_term_core (void)

em_status_t	em_term (void)

uint16_t	em_device_id (void)

em_status_t	em_cfgfile_opts (em_cfgfile_opts_t *cfgfile_opts)

void	em_cfgfile_opts_print (void)

Detailed Description

Event Machine initialization and termination

The Event Machine must be initialized before use. One thread (or process) that will be part of EM needs to call em_init(). Additionally, after the user has set up the participating threads and pinned them to HW-cores, each thread needs to run em_init_local() to become EM-cores. Only now is an EM-core ready to use the other EM API functions and can finally enter the dispatch-loop on each EM-core via one of the em_dispatch...() APIs to start handling events.

The EM termination sequence runs in the opposite order: each EM-core needs to call em_term_local() before one last call to em_term().

Typedef Documentation

◆ em_input_poll_func_t

typedef int(* em_input_poll_func_t) (void)

Input poll function - poll various input sources for pkts/events and enqueue into EM.

User provided function - EM calls this, if not NULL, in the dispatch loop on each core - set via 'em_conf_local_t::input_poll_fn'

Returns: number of pkts/events received from input and enqueued into EM

Definition at line 277 of file event_machine_init.h.

◆ em_output_drain_func_t

typedef int(* em_output_drain_func_t) (void)

'Periodical' draining of output from EM, if needed.

User provided function - EM calls this, if not NULL, in the dispatch loop on each core - set via 'em_conf_local_t::output_drain_fn'

Draining of output events/pkts: EM will every once in a while call this user provided function to ensure that low rate buffered output is eventually sent out. Not needed if your EM output queues (EM_QUEUE_TYPE_OUTPUT) always sends all events out. Useful in situations where output is buffered and sent out in bursts when enough output has been gathered - single events or low rate flows may, without this function, never be sent out (or too late) if the buffering threshold has not been reached.

Returns: number of events successfully drained and sent for output

Definition at line 295 of file event_machine_init.h.

Function Documentation

◆ em_cfgfile_opts()

em_status_t em_cfgfile_opts ( em_cfgfile_opts_t * cfgfile_opts )

Retrieve current EM config file options

This function populates cfgfile_opts with the configuration options read from the config file specified by the EM_CONFIG_FILE environment variable. If an option is not set in the config file, the default value defined in config/em-odp.conf is used. The function can be called only after a successful call to em_init().

See the documentation of each option for more details in config/em-odp.conf.

Parameters

[out] cfgfile_opts Filled with the combined options from the default config file and the config file specified by EM_CONFIG_FILE

Returns: EM_OK if the configuration is written to cfgfile_opts successfully

Definition at line 631 of file event_machine_init.c.

◆ em_cfgfile_opts_print()

void em_cfgfile_opts_print ( void )

Print EM config options set in the config file.

Definition at line 644 of file event_machine_init.c.

◆ em_conf_init()

void em_conf_init ( em_conf_t * conf )

Initialize configuration parameters for em_init()

Initialize em_conf_t to default values for all fields. After initialization, the user further needs to set the mandatory fields of 'em_conf_t' before calling em_init(). Always initialize 'conf' first with em_conf_init(&conf) to ensure backwards compatibility with potentially added new options.

Parameters

conf	Address of the em_conf_t to be initialized

See also: em_init()

Examples: bench_event.c, bench_pool.c, and dyn_cores.c.

Definition at line 135 of file event_machine_init.c.

◆ em_conf_local_init()

void em_conf_local_init ( em_conf_local_t * conf_local )

Initialize configuration parameters for em_init_local()

Initialize em_conf_local_t to default values for all fields. After initialization, the user further needs to set the mandatory fields of 'em_conf_local_t' before calling em_init_local(). Always initialize 'conf_local' first with em_conf_local_init(&conf_local) to ensure backwards compatibility with potentially added new options.

Parameters

conf_local Address of the em_conf_local_t to be initialized

See also: em_init_local()

Examples: bench_event.c, bench_pool.c, and dyn_cores.c.

Definition at line 339 of file event_machine_init.c.

◆ em_conf_local_opts()

em_status_t em_conf_local_opts ( em_conf_local_t * conf_local_opts )

Retrieve EM core-local configuration options given to em_init_local() or used by em_init_core().

This function returns the configurations of the calling EM-core and can be called only after a successful call to em_init_local()/em_init_core().

Note: Retrieving configurations for cores other than the calling core is not supported.

Parameters

[out] conf_local_opts Filled with EM core-local configuration options given to em_init_local() or used by em_init_core().

Returns: EM_OK if the configuration is written to conf_local_opts successfully

Definition at line 415 of file event_machine_init.c.

◆ em_conf_local_opts_print()

void em_conf_local_opts_print ( void )

Print EM core-local configuration options given to em_init_local() or used by em_init_core().

Note: This function prints configurations of the calling EM-core and can be called only after a successful call to em_init_local() or em_init_core(). Printing configurations for cores other than the calling core is not supported.

Definition at line 430 of file event_machine_init.c.

◆ em_conf_opts()

em_status_t em_conf_opts ( em_conf_t * conf_opts )

Retrieve EM configuration options given to em_init()

This function returns the configuration options that were provided to em_init() at initialization time. The function can be called only after a successful call to em_init().

See the documentation of each option in em_conf_t for more details.

Parameters

[out] conf_opts Filled with EM configuration options given to em_init()

Returns: EM_OK if the configuration is written to conf_opts successfully

Definition at line 321 of file event_machine_init.c.

◆ em_conf_opts_print()

void em_conf_opts_print ( void )

Print EM configuration options given to em_init().

Definition at line 334 of file event_machine_init.c.

◆ em_device_id()

uint16_t em_device_id ( void )

Return the EM device-id for this instance.

This is a convenience function that returns the EM device-id given by the user to em_init() via the em_conf_t::device_id field.

The function should only be called after a successful EM initialization.

Returns: the device-id of this EM instance.

Definition at line 626 of file event_machine_init.c.

◆ em_init()

em_status_t em_init ( const em_conf_t * conf )

Initialize the Event Machine.

Must be called once at startup. Additionally an EM-core needs to call the em_init_local() (or the older em_init_core()) function before using any further EM API functions/resources.

Parameters

conf	EM global config options

Returns: EM_OK if successful.

See also: em_init_local() for EM-core specific Initialization and termination after em_init().

Examples: bench_event.c, bench_pool.c, and dyn_cores.c.

Definition at line 147 of file event_machine_init.c.

◆ em_init_core()

em_status_t em_init_core ( void )

Initialize the current thread/process as a worker EM-core.

EM resources can be created after a successful call to this function and the worker EM-core can start dispatching events.

Note: The thread or process must be pinned to a unique physical core before running em_init_core().; Prefer using the newer em_init_local()/em_term_local() sequence over the older em_init_core()/em_term_core().

Using this function is similar to em_init_local(em_conf_local_t::core_type=EM_CORE_TYPE_WORKER) without the extra options provided by 'em_conf_local_t'.

Returns: EM_OK if successful.

See also: em_init()

Definition at line 441 of file event_machine_init.c.

◆ em_init_local()

em_status_t em_init_local ( const em_conf_local_t * conf_local )

Initialize the current thread/process as a worker, control or external EM-core.

Must be called once by each thread/process that needs access to EM resources within the instance.

Note

Pin the thread or process to the desired physical cpu(s)/core(s) before calling this function. The pinning depends on the EM-core type set in 'em_conf_local_t::core_type':

EM_CORE_TYPE_WORKER: pin to a unique physical cpu/core allowed by 'em_conf_t::phys_mask' as given to em_init().
EM_CORE_TYPE_CONTROL: pin to a set of cpus/cores allowed by 'em_conf_t::phys_mask' as given to em_init().
EM_CORE_TYPE_EXTERNAL: no restrictions on pinning.

em_conf_local_init(&conf_local) must be called before setting the mandatory fields of 'em_conf_local_t' and calling em_init_local().

Parameters

conf_local

Returns: EM_OK if successful.

See also: em_core_type_t for a description of the core types.

Examples: bench_event.c, bench_pool.c, and dyn_cores.c.

Definition at line 351 of file event_machine_init.c.

◆ em_term()

em_status_t em_term ( void )

Terminate the Event Machine.

Called once at exit. Additionally, before the one final call to em_term(), each EM-core (and EM external thread) needs to call the em_term_local() function to free up local resources.

Returns: EM_OK if successful.

See also: em_term_core() for EM-core specific termination before em_term().

Examples: bench_event.c, bench_pool.c, and dyn_cores.c.

Definition at line 545 of file event_machine_init.c.

◆ em_term_core()

em_status_t em_term_core ( void )

Local terminatation of a worker EM-core.

Local termination on a worker EM-core initialized by em_init_core() (or by em_init_local(em_conf_local_t::core_type=EM_CORE_TYPE_WORKER)). Local termination is required on all EM-cores before one call to em_term().

Note: Prefer using the newer em_init_local()/em_term_local() sequence over the older em_init_core()/em_term_core().

The EM-core will leave all queue groups before returning.

Returns: EM_OK if successful.

See also: em_term()

Examples: dyn_cores.c.

Definition at line 522 of file event_machine_init.c.

◆ em_term_local()

em_status_t em_term_local ( const em_term_local_t * term_local )

Local terminatation of a thread set up to run EM

Local termination is required by each worker, control and external EM-core before one call to em_term().

The EM worker and control cores will leave all queue groups before returning.

Note: em_term_local_init(&term_local) must be called before setting the fields of 'em_term_local_t' and calling em_term_local().

Returns: EM_OK if successful

Examples: bench_event.c, bench_pool.c, and dyn_cores.c.

Definition at line 482 of file event_machine_init.c.

◆ em_term_local_init()

void em_term_local_init ( em_term_local_t * term_local )

Initialize configuration parameters for em_term_local()

Initialize em_term_local_t to default values for all fields. After initialization, the user further needs to set the mandatory fields of 'em_term_local_t' before calling em_term_local(). Always initialize 'term_local' first with em_term_local_init(&term_local) to ensure backwards compatibility with potentially added new options.

Parameters

term_local Address of the em_term_local_t to be initialized

See also: em_term_local()

Examples: bench_event.c, bench_pool.c, and dyn_cores.c.

Definition at line 470 of file event_machine_init.c.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ em_input_poll_func_t

◆ em_output_drain_func_t

Function Documentation

◆ em_cfgfile_opts()

◆ em_cfgfile_opts_print()

◆ em_conf_init()

◆ em_conf_local_init()

◆ em_conf_local_opts()

◆ em_conf_local_opts_print()

◆ em_conf_opts()

◆ em_conf_opts_print()

◆ em_device_id()

◆ em_init()

◆ em_init_core()

◆ em_init_local()

◆ em_term()

◆ em_term_core()

◆ em_term_local()

◆ em_term_local_init()