Data Structures
struct	em_eo_conf_t

struct	em_eo_param_t

struct	em_eo_multircv_param_t

Macros
#define	em_eo_get_name em_eo_name

#define	em_eo_get_context em_eo_context

#define	em_eo_get_state em_eo_state

#define	em_eo_get_first em_eo_first

#define	em_eo_get_next em_eo_next

#define	em_eo_queue_get_first em_eo_queue_first

#define	em_eo_queue_get_next em_eo_queue_next

Typedefs
typedef void(*	em_receive_func_t) (void eo_ctx, em_event_t event, em_event_type_t type, em_queue_t queue, void q_ctx)

typedef void(*	em_receive_multi_func_t) (void eo_ctx, em_event_t events[], int num, em_queue_t queue, void q_ctx)

typedef em_status_t(*	em_start_func_t) (void eo_ctx, em_eo_t eo, const em_eo_conf_t conf)

typedef em_status_t(*	em_start_local_func_t) (void *eo_ctx, em_eo_t eo)

typedef em_status_t(*	em_stop_local_func_t) (void *eo_ctx, em_eo_t eo)

typedef em_status_t(*	em_stop_func_t) (void *eo_ctx, em_eo_t eo)

Enumerations
enum	em_eo_start_local_mode_t { EM_EO_START_LOCAL_MODE_CONFIG_FILE = 0 , EM_EO_START_LOCAL_MODE_INIT_NORUN , EM_EO_START_LOCAL_MODE_INIT_RUN , EM_EO_START_LOCAL_MODE_LAST }

enum	em_eo_stop_local_mode_t { EM_EO_STOP_LOCAL_MODE_CONFIG_FILE = 0 , EM_EO_STOP_LOCAL_MODE_TERM_NORUN , EM_EO_STOP_LOCAL_MODE_TERM_RUN , EM_EO_STOP_LOCAL_MODE_LAST }

enum	em_eo_state_t { EM_EO_STATE_UNDEF = 0 , EM_EO_STATE_CREATED = 1 , EM_EO_STATE_STARTING = 2 , EM_EO_STATE_RUNNING = 3 , EM_EO_STATE_STOPPING = 4 , EM_EO_STATE_ERROR = 5 }

Functions
em_eo_t	em_eo_create (const char name, em_start_func_t start, em_start_local_func_t local_start, em_stop_func_t stop, em_stop_local_func_t local_stop, em_receive_func_t receive, const void eo_ctx)

void	em_eo_param_init (em_eo_param_t *param)

em_eo_t	em_eo_create_param (const char name, const em_eo_param_t param)

void	em_eo_multircv_param_init (em_eo_multircv_param_t *param)

em_eo_t	em_eo_create_multircv (const char name, const em_eo_multircv_param_t param)

em_status_t	em_eo_delete (em_eo_t eo)

size_t	em_eo_name (em_eo_t eo, char *name, size_t maxlen)

em_eo_t	em_eo_find (const char *name)

em_status_t	em_eo_add_queue (em_eo_t eo, em_queue_t queue, int num_notif, const em_notif_t notif_tbl[])

em_status_t	em_eo_add_queue_sync (em_eo_t eo, em_queue_t queue)

em_status_t	em_eo_remove_queue (em_eo_t eo, em_queue_t queue, int num_notif, const em_notif_t notif_tbl[])

em_status_t	em_eo_remove_queue_sync (em_eo_t eo, em_queue_t queue)

em_status_t	em_eo_remove_queue_all (em_eo_t eo, int delete_queues, int num_notif, const em_notif_t notif_tbl[])

em_status_t	em_eo_remove_queue_all_sync (em_eo_t eo, int delete_queues)

em_status_t	em_eo_register_error_handler (em_eo_t eo, em_error_handler_t handler)

em_status_t	em_eo_unregister_error_handler (em_eo_t eo)

em_status_t	em_eo_start (em_eo_t eo, em_status_t result, const em_eo_conf_t conf, int num_notif, const em_notif_t notif_tbl[])

em_status_t	em_eo_start_sync (em_eo_t eo, em_status_t result, const em_eo_conf_t conf)

em_status_t	em_eo_stop (em_eo_t eo, int num_notif, const em_notif_t notif_tbl[])

em_status_t	em_eo_stop_sync (em_eo_t eo)

em_eo_t	em_eo_current (void)

void *	em_eo_context (em_eo_t eo)

em_eo_state_t	em_eo_state (em_eo_t eo)

em_eo_t	em_eo_first (unsigned int *num)

em_eo_t	em_eo_next (void)

em_queue_t	em_eo_queue_first (unsigned int *num, em_eo_t eo)

em_queue_t	em_eo_queue_next (void)

uint64_t	em_eo_to_u64 (em_eo_t eo)

Detailed Description

Operations on EOs

Execution objects (EO) are the application building blocks of EM. An EO typically implements one logical function or one stage in a pipeline, but alternatively the whole application could be implemented with one EO. EOs work as servers, queues are the service access points (inputs to the EO).

An EO consists of user provided callback functions and context data. The most important function is the receive function, which gets called when an event is received from one of the queues associated with the EO. The EM scheduler selects the next event for processing on a core and the EM dispatcher on that core maps the received event and queue information to an EO receive function to call to process the event. Other EO functions are used to manage start-up and teardown of EOs. See individual EO functions for more details.

                  em_eo_create()
                        |
                        v
                 .-------------.
     .->.------->|   CREATED   | new events discarded
     |  |        '-------------'
     |  |               | em_eo_start(+notifs) / em_eo_start_sync()
     |  |               v
     |  |        .-------------.
     |  |        |   STARTING  | new events discarded
     |  '        '-------------'
     |   \         global start
     |    \            THEN
     |     \       local start on each core
     |      '--- FAIL   OK
     |                  | send 'start-completed' notifications
     |                  v
     .           .-------------.
     |           |   RUNNING   | events processed by the receive function
     |           '-------------'
     |                  | em_eo_stop(+notifs) / em_eo_stop_sync()
     |                  v
     '           .-------------.
      \          |   STOPPING  | new events discarded
       \         '-------------'
        \               |
         \              v
          \         local stops on each core
           \           THEN
            \       global stops
             \          .
              \        /
               -------' send 'stop-completed' notifications

Macro Definition Documentation

◆ em_eo_get_context

#define em_eo_get_context em_eo_context

Definition at line 1126 of file event_machine_eo.h.

◆ em_eo_get_first

#define em_eo_get_first em_eo_first

Definition at line 1169 of file event_machine_eo.h.

◆ em_eo_get_name

#define em_eo_get_name em_eo_name

Definition at line 755 of file event_machine_eo.h.

◆ em_eo_get_next

#define em_eo_get_next em_eo_next

Definition at line 1185 of file event_machine_eo.h.

◆ em_eo_get_state

#define em_eo_get_state em_eo_state

Definition at line 1138 of file event_machine_eo.h.

◆ em_eo_queue_get_first

#define em_eo_queue_get_first em_eo_queue_first

Definition at line 1224 of file event_machine_eo.h.

◆ em_eo_queue_get_next

#define em_eo_queue_get_next em_eo_queue_next

Definition at line 1240 of file event_machine_eo.h.

Typedef Documentation

◆ em_receive_func_t

typedef void(* em_receive_func_t) (void *eo_ctx, em_event_t event, em_event_type_t type, em_queue_t queue, void *q_ctx)

Execution Object (EO) event receive function (single-event)

An application receives events through queues and these events are passed to the application's EO receive function(s) for processing. The EO receive function implements the main part of the application logic. EM calls the receive function when it has dequeued an event from one of the EO's queues. The application then processes the event and returns immediately in a run-to-completion fashion. There is no pre-emption.

On multicore systems, several events (from the same or different queue) may be dequeued in parallel and thus the same receive function may be executed concurrently on several cores. Parallel execution may be limited by queue group setup or by using queues with an atomic scheduling mode.

The EO and queue context pointers are user defined. The EO context is given at EO creation and the queue context is set with em_queue_set_context(). These contexts may be used in any way needed, the EM implementation will not dereference them. For example, the EO context may be used to store global EO state information, which is common to all queues and events for that EO. In addition, the queue context may be used to store queue specific state data (e.g. user data flow related data). The queue context data for an atomic queue can be freely manipulated in the receive function, since only one event at a time can be under work from that particular atomic queue. For other queue types it is up to the user to synchronize context access. The EO context is protected only if the EO has one queue and it is of type 'atomic' (applies also to several atomic queues that belong to the same atomic group).

An event (handle) must be converted to an event structure pointer with em_event_pointer() before accessing any data it may contain. The event type specifies the event structure in memory, which is implementation or application specific. The queue handle specifies the queue where the event was dequeued from.

The EO will not receive any events if it has not been successfully started.

Parameters

eo_ctx	EO context data as given to em_eo_create(), EM does not touch.
event	Event handle
type	Event type
queue	Queue from which the event was dequeued
q_ctx	Queue context data. The context pointer is set by em_queue_set_context(), EM does not touch the data.

See also: em_eo_create(), em_alloc(), em_free(), em_send(), em_event_pointer(), em_queue_set_context()

Examples: cli_top.c, fractal.c, hello.c, loop_united.c, and timer_hello.c.

Definition at line 147 of file event_machine_eo.h.

◆ em_receive_multi_func_t

typedef void(* em_receive_multi_func_t) (void *eo_ctx, em_event_t events[], int num, em_queue_t queue, void *q_ctx)

Execution Object (EO) multi-event receive function

Similar to the single-event receive function (em_receive_func_t), except that multiple events can be passed with one call to the EO receive function. A multi-event receive function is taken into use during EO creation with a call to em_eo_create_multircv(...). The maximum number of events that the multi-event EO receive function is prepared to handle can be passed with the argument 'max_events' of em_eo_create_multircv(). The EM dispatcher will split event batches larger than 'max_events' into chunks of 'max_events'.

Event group handling: All events passed by the EM dispatcher to the EO multi-event receive function belong to the same event group (or none) - a batch of events containing multiple event groups is split by the dispatcher into smaller chunks, each chunk belonging to the same event group (or none). The event group count is decremented by the number of events passed to the receive function when execution returns to the dispatcher.

Note: Contrary to the single-event EO receive function (em_receive_func_t), no event types are passed. Use appropriate event APIs if the event types are needed.

Parameters

eo_ctx	EO context data as given to em_eo_create_multircv(), EM does not touch.
events	Event handles: events[num]
num	Number of events received (0 to 'max_events' of em_eo_create_multircv())
queue	Queue from which the event was dequeued
q_ctx	Queue context data. The context pointer is set by em_queue_set_context(), EM does not touch the data.

See also: em_eo_create_multircv(), em_alloc(), em_free(), em_send(), em_event_pointer(), em_queue_set_context()

Definition at line 187 of file event_machine_eo.h.

◆ em_start_func_t

typedef em_status_t(* em_start_func_t) (void *eo_ctx, em_eo_t eo, const em_eo_conf_t *conf)

Execution Object (EO) start function, global.

This EO callback function is called once on one core by em_eo_start(). The purpose of this global EO-start is to provide a placeholder for first level EO initialization, e.g. allocating memory and initializing shared data. After this global start returns, the EO core local start function (if given) is called on all cores in the EM instance. If there is no core local start, then event dispatching is enabled as this function returns, otherwise the EO is enabled only when all core local starts have completed successfully on all the cores. If this function does not return EM_OK, the system will not call the core local init and will not enable event dispatching for this EO.

Note that events sent to scheduled queues from a start function are buffered. The buffered events will be sent into the queues when the EO start functions have returned - otherwise it would not be possible to send events to the EO's own queues as the EO is not yet in a started state. No buffering is done when sending to queues that are not scheduled.

The last argument is an optional startup configuration passed directly from em_eo_start/_sync(). If local start functions need the configuration data, it must be saved during the global start.

This function should never be directly called from the application, it will be called by em_eo_start(), which maintains state information.

Parameters

eo_ctx	EO context data as given to em_eo_create(), EM does not touch.
eo	EO handle
conf	Optional startup configuration, NULL ok.

Returns: EM_OK if successful, other values abort EO start

See also: em_eo_start(), em_eo_create()

Examples: cli_top.c, fractal.c, hello.c, and timer_hello.c.

Definition at line 238 of file event_machine_eo.h.

◆ em_start_local_func_t

typedef em_status_t(* em_start_local_func_t) (void *eo_ctx, em_eo_t eo)

Execution Object (EO) start function, EM-core local.

Similar to the global start function above, but is called after the global start function has completed and is run on all EM-cores (of types EM_CORE_TYPE_WORKER and EM_CORE_TYPE_CONTROL) of the EM instance and potentially in parallel. The local start function is not run on EM external threads/processes (of type EM_CORE_TYPE_EXTERNAL).

The purpose of this optional local start function is to work as a placeholder for EM-core local initialization, e.g. allocating EM-core local memory.

Note that events sent to scheduled queues from local start functions are buffered. The buffered events will be sent into the queues when the EO start functions have returned - otherwise it would not be possible to send events to the EO's own queues as the EO is not yet in a started state. No buffering is done when sending to queues that are not scheduled.

This function should never be directly called from the application, it will be called by em_eo_start/_sync(), which maintains state information.

Event dispatching is not enabled if this function doesn't return EM_OK on all cores.

Parameters

eo_ctx	EO context data as given to em_eo_create(), EM does not touch.
eo	EO handle

Returns: EM_OK if successful, other values prevent EO start

See also: em_eo_start(), em_eo_create()

Examples: cli_top.c, and timer_hello.c.

Definition at line 272 of file event_machine_eo.h.

◆ em_stop_func_t

typedef em_status_t(* em_stop_func_t) (void *eo_ctx, em_eo_t eo)

Execution Object (EO) stop function, global.

The EO global stop function is called once on one core after the optional core local stop functions return on all cores. The system disables event dispatching before calling this function and also makes sure it does not get called before all cores have been notified of the stop condition for this EO (don't dispatch new events).

This function should never be directly called from the application, it will be called by em_eo_stop(), which maintains state information.

Parameters

eo_ctx	EO context data as given to em_eo_create(), EM does not touch.
eo	EO handle

Returns: EM_OK if successful.

See also: em_eo_stop(), em_eo_create()

Examples: cli_top.c, fractal.c, hello.c, and timer_hello.c.

Definition at line 414 of file event_machine_eo.h.

◆ em_stop_local_func_t

typedef em_status_t(* em_stop_local_func_t) (void *eo_ctx, em_eo_t eo)

Execution Object (EO) stop function, EM-core local.

This function is called once on each EM-core (of type EM_CORE_TYPE_WORKER or EM_CORE_TYPE_CONTROL) of the EM instance before the global stop (reverse order of start). The local stop function is not run on EM external threads/processes (of type EM_CORE_TYPE_EXTERNAL). The system disables event dispatching before calling this function and also makes sure it does not get called before the core has been notified of the stop condition for this EO (won't dispatch any new events).

This function should never be directly called from the application, it will be called by em_eo_stop(), which maintains state information.

Parameters

eo_ctx	EO context data as given to em_eo_create(), EM does not touch.
eo	EO handle

Returns: EM_OK if successful.

See also: em_eo_stop(), em_eo_create()

Definition at line 344 of file event_machine_eo.h.

Enumeration Type Documentation

◆ em_eo_start_local_mode_t

enum em_eo_start_local_mode_t

Execution Object (EO) local start function mode.

The mode determines how & when the EO's local start function is run. An EO local start function, if provided, is run on all, at the time available, EM-cores (of type EM_CORE_TYPE_WORKER or EM_CORE_TYPE_CONTROL) as triggered by em_eo_start/_sync(). Adding an EM-core after the EO has already been started will not have the EO local start function triggered by em_eo_start/_sync() for the new EM-core, but the user may still want to have it run to properly initialize core local data. This option controls whether the EO's local start function is run during EM-core init when adding a new EM-core.

See also: em_eo_stop_local_mode_t

Enumerator
EM_EO_START_LOCAL_MODE_CONFIG_FILE	Use the EM config file setting from [em-odp.conf]: 'eo.start_local_fn_at_init = true/false'. This mode is set by em_eo_param_init() (default). The EM config file setting determines whether the local start functions for already started EOs are run during EM-core init when adding a new EM-core to an EM instance.
EM_EO_START_LOCAL_MODE_INIT_NORUN	Don't run the local start function during EM-core init. The EO's start and local start functions are only run when starting the EO via em_eo_start() or em_eo_start_sync(). Adding an EM-core after the EO has been started will NOT trigger any further start functions. Overrides the EM config file setting 'eo.start_local_fn_at_init' for the EO.
EM_EO_START_LOCAL_MODE_INIT_RUN	Run the local start function at EM-core init. Run the EO's local start function during EM-core init when a new EM-core is added to the EM instance, but only if the EO is already started/running (EM_EO_STATE_RUNNING). Overrides the EM config file setting 'eo.start_local_fn_at_init' for the EO.
EM_EO_START_LOCAL_MODE_LAST	Last, for bounds checking only

Definition at line 289 of file event_machine_eo.h.

◆ em_eo_state_t

enum em_eo_state_t

EO running state. Event dispatching is only enabled in running state.

Enumerator
EM_EO_STATE_UNDEF	Undefined
EM_EO_STATE_CREATED	Initial state after creation
EM_EO_STATE_STARTING	start called, not completed
EM_EO_STATE_RUNNING	running, event dispatching enabled
EM_EO_STATE_STOPPING	stop called, not completed. Next state EM_EO_STATE_CREATED
EM_EO_STATE_ERROR	exceptional state, only delete allowed

Definition at line 419 of file event_machine_eo.h.

◆ em_eo_stop_local_mode_t

enum em_eo_stop_local_mode_t

Execution Object (EO) local stop function mode.

The mode determines how & when the EO's local stop function is run. An EO local stop function, if provided, is run on all, at the time available, EM-cores (of type EM_CORE_TYPE_WORKER or EM_CORE_TYPE_CONTROL) as triggered by em_eo_stop/_sync(). Removing an EM-core before the EO has been stopped will not have the EO local stop function triggered by em_eo_stop/_sync(), but the user may still want to have it run to properly clean up EM-core local data. This option controls whether the EO's local stop function is run during EM-core termination when removing an EM-core.

See also: em_eo_start_local_mode_t

Enumerator
EM_EO_STOP_LOCAL_MODE_CONFIG_FILE	Use the EM config file setting from [em-odp.conf]: 'eo.stop_local_fn_at_term = true/false'. This mode is set by em_eo_param_init() (default). The EM config file setting determines whether the local stop functions for EOs are run during EM-core termination when removing an EM-core from an EM instance while the EO is still otherwise running.
EM_EO_STOP_LOCAL_MODE_TERM_NORUN	Don't run the local stop function during EM-core termination. The EO's stop and local stop functions are only run when stopping the EO via em_eo_stop() or em_eo_stop_sync(). Removing an EM-core while the EO is running will NOT trigger any further stop functions. Overrides the EM config file setting 'eo.stop_local_fn_at_term' for the EO.
EM_EO_STOP_LOCAL_MODE_TERM_RUN	Run the local stop function for this EO during EM-core term. Run the EO's local stop function during EM-core termination when an EM-core is removed from the EM instance, but only if the EO is already started/running (EM_EO_STATE_RUNNING). Overrides the EM config file setting 'eo.stop_local_fn_at_term' for the EO.
EM_EO_STOP_LOCAL_MODE_LAST	Last, for bounds checking only

Definition at line 361 of file event_machine_eo.h.

Function Documentation

◆ em_eo_add_queue()

em_status_t em_eo_add_queue	(	em_eo_t	eo,
		em_queue_t	queue,
		int	num_notif,
		const em_notif_t	notif_tbl[]
	)

Add a queue to an Execution Object (EO), asynchronous (non-blocking)

Add the given queue to the EO and enable scheduling for it. The function returns immediately, but the operation can be asynchronous and only fully complete later. The given notification events are sent when the operation has completed and the queue is ready to receive events. Note, that the completion notification(s) guarantee that the queue itself is operational, but if the target EO is not yet started then events sent into the queue will still be dropped by dispatcher.

Parameters

eo	EO handle
queue	Queue handle
num_notif	Number of notification events, 0 for no notification
notif_tbl	Array of pairs of event and queue identifiers (+ optional event groups to send the events with)

Returns: EM_OK if successful.

See also: em_queue_create(), em_eo_create(), em_eo_remove_queue(), em_eo_add_queue_sync()

Definition at line 430 of file event_machine_eo.c.

◆ em_eo_add_queue_sync()

em_status_t em_eo_add_queue_sync	(	em_eo_t	eo,
		em_queue_t	queue
	)

Add a queue to an Execution Object (EO), synchronous (blocking)

As em_eo_add_queue(), but does not return until the queue is ready to receive events.

Note that the function is blocking and will not return until the operation has completed across all concerned EM cores. Sync-API calls can block the core for a long (indefinite) time, thus they should not be used to make runtime changes on real time EM cores - consider the async variants of the APIs in these cases instead. While one core is calling a sync-API function, the others must be running the EM dispatch loop to be able to receive and handle the sync-API request events sent internally. Use the sync-APIs mainly to simplify application start-up or teardown.

Parameters

eo	EO handle
queue	Queue handle

Returns: EM_OK if successful.

See also: em_queue_create(), em_eo_create(), em_eo_remove_queue(); em_eo_add_queue() for an asynchronous version of the API

Definition at line 438 of file event_machine_eo.c.

◆ em_eo_context()

void * em_eo_context ( em_eo_t eo )

Get Execution Object (EO) specific (application) context.

Returns the EO context pointer that the application has earlier provided via em_eo_create/_param() or em_eo_create_multircv() for the given EO.

Parameters

eo	EO for which the context is requested

Returns: EO specific context pointer or NULL if no context (or error)

Examples: api_hooks.c, queue_types_ag.c, queue_types_local.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 1177 of file event_machine_eo.c.

◆ em_eo_create()

em_eo_t em_eo_create	(	const char *	name,
		em_start_func_t	start,
		em_start_local_func_t	local_start,
		em_stop_func_t	stop,
		em_stop_local_func_t	local_stop,
		em_receive_func_t	receive,
		const void *	eo_ctx
	)

Create an Execution Object (EO).

Allocate an EO handle and initialize internal data for the new EO. The EO is left in a non-active state, i.e. no events are dispatched before em_eo_start() has been called. Start, stop and receive callback functions are mandatory arguments.

The EO name is copied into EO internal data. The maximum length stored is EM_EO_NAME_LEN. Duplicate names are allowed, but find will only match one of them.

Note: The EO start/stop local function mode is read from the EM config file setting 'eo.start_local_fn_at_init' and 'eo.stop_local_fn_at_term' when using this API. Consider using the newer API em_eo_create_params() instead for more control.

Parameters

name	Name of the EO (optional, NULL ok)
start	Start function
local_start	Core local start function (NULL if no local start)
stop	Stop function
local_stop	Core local stop function (NULL if no local stop)
receive	Receive function
eo_ctx	User defined EO context data, EM passes the value (NULL if no context)

Returns: New EO handle if successful, otherwise EM_EO_UNDEF.

Return values

EM_EO_UNDEF on error

See also: em_eo_start(), em_eo_delete(), em_queue_create(), em_eo_add_queue(); em_start_func_t, em_stop_func_t, em_receive_func_t; em_eo_create_param(), em_eo_create_multircv()

Definition at line 173 of file event_machine_eo.c.

◆ em_eo_create_multircv()

em_eo_t em_eo_create_multircv	(	const char *	name,
		const em_eo_multircv_param_t *	param
	)

Create an Execution Object (EO) with a multi-event receive function.

Similar to em_eo_create(), except that an EO multi-event receive function is taken into use for the created EO, see em_receive_multi_func_t (passed via em_eo_multircv_param_t param).

Always initialize 'param' first with em_eo_multircv_param_init(&param) to ensure backwards compatibility before setting your own params and calling em_eo_create_multircv():

em_eo_multircv_param_t param;
em_eo_t eo;
 
em_eo_multircv_param_init(&param);
param.start = my_start_fn;
param.stop = my_stop_fn;
param.receive_multi = my_receive_multi_fn;
param.max_events = MY_MAX_EVENTS; // or use default=0
...
eo = em_eo_create_multircv("my-eo", &param);
if (unlikely(eo == EM_EO_UNDEF))
   report_error();

Parameters

name	Name of the EO (optional, NULL ok)
param	EO parameters

Returns: New EO handle if successful, otherwise EM_EO_UNDEF.

See also: em_eo_multircv_param_init(); em_eo_start(), em_eo_start_sync(), em_eo_stop(), em_eo_stop_sync(); em_start_func_t, em_stop_func_t, em_receive_multi_func_t

Examples: event_types.c, and loop_united.c.

Definition at line 216 of file event_machine_eo.c.

◆ em_eo_create_param()

em_eo_t em_eo_create_param	(	const char *	name,
		const em_eo_param_t *	param
	)

Create an Execution Object (EO) with parameters

Allocate an EO handle and initialize internal data for the new EO. The EO is left in a non-active state, i.e. no events are dispatched before em_eo_start/_sync() has been called.

The EO name is copied into EO internal data. The maximum length stored is EM_EO_NAME_LEN. Duplicate names are allowed, but find will only match one of them.

Always initialize 'param' first with em_eo_param_init(&param) to ensure backwards compatibility and default values for all fields before setting your own params and calling em_eo_create_param():

em_eo_param_t param;
em_eo_t eo;
 
em_eo_param_init(&param); - Set default values for all fields
param.start = my_start_fn;
param.stop = my_stop_fn;
param.receive = my_receive_fn;
...
eo = em_eo_create_param("my-eo", &param);
if (unlikely(eo == EM_EO_UNDEF))
   report_error();

Parameters

name	Name of the EO (optional, NULL ok)
param	EO parameters

Returns: New EO handle if successful, otherwise EM_EO_UNDEF.

Return values

EM_EO_UNDEF on error

Examples: dyn_cores.c.

Definition at line 197 of file event_machine_eo.c.

◆ em_eo_current()

em_eo_t em_eo_current ( void )

Return the currently active Execution Object (EO)

Returns the EO handle associated with the currently running EO function. Only valid if called within an EO-context, will return EM_EO_UNDEF otherwise. Can be called from the EO-receive or EO-start/stop functions (or subfunctions thereof). Note that calling em_eo_current() from e.g. an EO-start function that was launched from within another EO's receive will return the EO handle of the EO being started - i.e. always returns the 'latest' current EO.

Returns: The current EO or EM_EO_UNDEF if no current EO (or error)

Examples: api_hooks.c, queue_types_ag.c, and queue_types_local.c.

Definition at line 1172 of file event_machine_eo.c.

◆ em_eo_delete()

em_status_t em_eo_delete ( em_eo_t eo )

Delete an Execution Object (EO).

Immediately delete the given EO and free the identifier.

NOTE, that an EO can only be deleted after it has been stopped using em_eo_stop() with notifications or em_eo_stop_sync(), otherwise another core might still access the EO data. All associated queues must be removed before deleting an EO.

A sequence of

em_eo_stop_sync(eo);
em_eo_remove_queue_all_sync(eo, EM_TRUE);
em_eo_delete(eo);

will cleanly delete an EO from the EM point of view (not including user allocated data).

Parameters

eo	EO handle to delete

Returns: EM_OK if successful.

See also: em_eo_stop(), em_eo_remove_queue()

Definition at line 301 of file event_machine_eo.c.

◆ em_eo_find()

em_eo_t em_eo_find ( const char * name )

Find Execution Object (EO) by name.

Finds an EO by the given name (exact match). An empty string will not match anything. The search is case sensitive. This function will return the first match only if there are duplicate names.

Parameters

name	the name to look for

Returns: EO handle or EM_EO_UNDEF if not found

See also: em_eo_create()

Examples: cli_top.c, timer_hello.c, timer_test.c, timer_test_periodic.c, and timer_test_ring.c.

Definition at line 359 of file event_machine_eo.c.

◆ em_eo_first()

em_eo_t em_eo_first ( unsigned int * num )

Initialize Execution Object (EO) iteration and return the first EO handle.

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

unsigned int num;
em_eo_t eo = em_eo_first(&num);
while (eo != EM_EO_UNDEF) {
   eo = em_eo_next();
}

Parameters

[out] num Pointer to an unsigned int to store the amount of EOs into

Returns: The first EO handle or EM_EO_UNDEF if none exist

See also: em_eo_next()

Examples: queue_types_ag.c.

Definition at line 1224 of file event_machine_eo.c.

◆ em_eo_multircv_param_init()

void em_eo_multircv_param_init ( em_eo_multircv_param_t * param )

Initialize parameters for the Execution Object (EO) with a multi-event receive-function.

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

Parameters

param Address of the em_eo_multircv_param_t to be initialized

See also: em_eo_create_multircv()

Examples: event_types.c, and loop_united.c.

Definition at line 202 of file event_machine_eo.c.

◆ em_eo_name()

size_t em_eo_name	(	em_eo_t	eo,
		char *	name,
		size_t	maxlen
	)

Returns the name given to the Execution Object (EO) when it was created.

A copy of the name string (up to 'maxlen' characters) is written to the user buffer 'name'. The string is always null terminated - even if the given buffer length is less than the name length.

The function returns 0 and writes an empty string if the EO has no name.

Parameters

	eo	EO handle
[out]	name	Destination buffer
	maxlen	Maximum length (including the terminating '0')

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

See also: em_eo_create()

Examples: api_hooks.c, atomic_processing_end.c, dispatcher_callback.c, dyn_cores.c, error.c, fractal.c, hello.c, and queue_types_ag.c.

Definition at line 331 of file event_machine_eo.c.

◆ em_eo_next()

em_eo_t em_eo_next ( void )

Return the next Execution Object (EO) handle.

Continues the EO iteration started by em_eo_first() and returns the next EO handle.

Returns: The next EO handle or EM_EO_UNDEF if the EO iteration is completed (i.e. no more EO's available).

See also: em_eo_first()

Examples: queue_types_ag.c.

Definition at line 1247 of file event_machine_eo.c.

◆ em_eo_param_init()

void em_eo_param_init ( em_eo_param_t * param )

Initialize parameters for Execution Object (EO) creation.

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

Parameters

param Address of the em_eo_param_t to be initialized

See also: em_eo_create_param()

Examples: dyn_cores.c.

Definition at line 161 of file event_machine_eo.c.

◆ em_eo_queue_first()

em_queue_t em_eo_queue_first	(	unsigned int *	num,
		em_eo_t	eo
	)

Initialize iteration of an Execution Object's (EO) queues and return the first queue handle.

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

Parameters

[out]	num	Output the current amount of queues associated with the EO
	eo	EO handle

Returns: The first queue handle or EM_QUEUE_UNDEF if none exist or the EO is invalid.

See also: em_eo_queue_next()

Examples: queue_types_ag.c.

Definition at line 1264 of file event_machine_eo.c.

◆ em_eo_queue_next()

em_queue_t em_eo_queue_next ( void )

Return the Execution Object's (EO) next queue handle.

Continues the queue iteration started by em_eo_queue_first() and returns the next queue handle owned by the EO.

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

See also: em_eo_queue_first()

Examples: queue_types_ag.c.

Definition at line 1310 of file event_machine_eo.c.

◆ em_eo_register_error_handler()

em_status_t em_eo_register_error_handler	(	em_eo_t	eo,
		em_error_handler_t	handler
	)

Register an Execution Object (EO) specific error handler.

The EO specific error handler is called if an error occurs or em_error() is called in the context of the running EO. Note, the provided function will override any previously registered error handler for the EO in question. The global error handler is called if no EO specific error handler is registered.

Parameters

eo	EO handle
handler	New error handler

Returns: EM_OK if successful.

See also: em_register_error_handler(), em_error_handler_t()

Examples: error.c, event_group_abort.c, and timer_test.c.

Definition at line 747 of file event_machine_eo.c.

◆ em_eo_remove_queue()

em_status_t em_eo_remove_queue	(	em_eo_t	eo,
		em_queue_t	queue,
		int	num_notif,
		const em_notif_t	notif_tbl[]
	)

Removes a queue from an Execution Object (EO), asynchronous (non-blocking)

Disables queue scheduling and removes the queue from the EO. The function returns immediately, but the operation can be asynchronous and only fully complete later. The given notification events are sent when the operation has completed across all cores and no event from this queue is being dispatched anymore. Use notifications to know when the operation has fully completed and the queue can safely be deleted.

Parameters

eo	EO handle
queue	Queue handle to remove
num_notif	Number of notification events, 0 for no notification
notif_tbl	Array of pairs of event and queue identifiers (+ optional event groups to send the events with)

Returns: EM_OK if successful.

See also: em_eo_add_queue(), em_eo_remove_queue_sync()

Definition at line 446 of file event_machine_eo.c.

◆ em_eo_remove_queue_all()

em_status_t em_eo_remove_queue_all	(	em_eo_t	eo,
		int	delete_queues,
		int	num_notif,
		const em_notif_t	notif_tbl[]
	)

Removes all queues from an Execution Object (EO), asynchronous (non-blocking)

Like em_eo_remove_queue(), but removes all queues currently associated with the EO. The argument 'delete_queues' can be used to automatically also delete all queues by setting it to EM_TRUE (EM_FALSE otherwise). Note: any allocated queue contexts will still need to be handled elsewhere.

Parameters

eo	EO handle
delete_queues	delete the EO's queues if set to EM_TRUE
num_notif	Number of notification events, 0 for no notification
notif_tbl	Array of pairs of event and queue identifiers (+ optional event groups to send the events with)

Returns: EM_OK if successful.

See also: em_eo_add_queue(), em_eo_remove_queue_sync(), em_eo_remove_queue_all_sync()

Definition at line 619 of file event_machine_eo.c.

◆ em_eo_remove_queue_all_sync()

em_status_t em_eo_remove_queue_all_sync	(	em_eo_t	eo,
		int	delete_queues
	)

Removes all queues from an Execution Object (EO), synchronous (blocking).

As em_eo_remove_queue_all(), but does not return until all queues have been removed.

Note that the function is blocking and will not return until the operation has completed across all concerned EM cores. Sync-API calls can block the core for a long (indefinite) time, thus they should not be used to make runtime changes on real time EM cores - consider the async variants of the APIs in these cases instead. While one core is calling a sync-API function, the others must be running the EM dispatch loop to be able to receive and handle the sync-API request events sent internally. Use the sync-APIs mainly to simplify application start-up or teardown.

Parameters

eo	EO handle
delete_queues	delete the EO's queues if set to EM_TRUE

Returns: EM_OK if successful.

See also: em_eo_remove_queue_all() for an asynchronous version of the API

Definition at line 672 of file event_machine_eo.c.

◆ em_eo_remove_queue_sync()

em_status_t em_eo_remove_queue_sync	(	em_eo_t	eo,
		em_queue_t	queue
	)

Removes a queue from an Execution Object (EO), synchronous (blocking)

As em_eo_remove_queue(), but will not return until the queue has been disabled, removed from the EO and no more events are being processed from the queue.

Note that the function is blocking and will not return until the operation has completed across all concerned EM cores. Sync-API calls can block the core for a long (indefinite) time, thus they should not be used to make runtime changes on real time EM cores - consider the async variants of the APIs in these cases instead. While one core is calling a sync-API function, the others must be running the EM dispatch loop to be able to receive and handle the sync-API request events sent internally. Use the sync-APIs mainly to simplify application start-up or teardown.

Parameters

eo	EO handle
queue	Queue handle to remove

Returns: EM_OK if successful.

See also: em_eo_remove_queue() for an asynchronous version of the API

Examples: api_hooks.c, dispatcher_callback.c, dyn_cores.c, hello.c, queue_group.c, and queue_groups.c.

Definition at line 520 of file event_machine_eo.c.

◆ em_eo_start()

em_status_t em_eo_start	(	em_eo_t	eo,
		em_status_t *	result,
		const em_eo_conf_t *	conf,
		int	num_notif,
		const em_notif_t	notif_tbl[]
	)

Start an Execution Object (EO), asynchronous (non-blocking)

Start and enable a previously created EO. The em_eo_start() function will first call the user provided global EO start function. If that global start function returns EM_OK then events to trigger the (optional) user provided local start function are sent to all EM-cores. The em_eo_start() function returns immediately after the global start returns, which means that the action only fully completes later. Notifications should be used if the caller needs to know when the EO start has fully completed. The given notification event(s) will be sent to the given queue(s) when the start is completed on all cores.

The EO's global start function can be called on any core type, i.e. also on EM_CORE_TYPE_EXTERNAL if em_eo_start() is called from there.

Local start is not called and event dispatching is not enabled for this EO if the global start function does not return EM_OK.

The notification(s) are sent when the global start function returns if a local start function hasn't been provided. Use '0' as 'num_notif' if notifications are not needed. Be aware of, is this case, that the EO may not immediately be ready to handle events.

Note that events sent to scheduled queues from a user provided EO global or local start function are buffered. The buffered events will be sent into the queues when the EO start functions have all returned - otherwise it would not be possible to send events to the EO's own queues as the EO is not yet in a started state. No buffering is done when sending to queues that are not scheduled.

The optional conf-argument can be used to pass applification specific information (e.g. configuration data) to the EO.

Parameters

	eo	EO handle
[out]	result	Optional pointer to em_status_t, which gets updated to the return value of the actual user provided EO global start function.
	conf	Optional startup configuration, NULL ok.
	num_notif	If not 0, defines the number of notification events to send when all cores have returned from the start function(s).
	notif_tbl	Array of em_notif_t, the optional notification events (array data is copied)

Returns: EM_OK if successful.

See also: em_start_func_t(), em_start_local_func_t(), em_eo_stop(), em_eo_start_sync()

Examples: queue_group.c.

Definition at line 785 of file event_machine_eo.c.

◆ em_eo_start_sync()

em_status_t em_eo_start_sync	(	em_eo_t	eo,
		em_status_t *	result,
		const em_eo_conf_t *	conf
	)

Start Execution Object (EO), synchronous (blocking)

As em_eo_start(), but will not return until the operation is complete.

Note that the function is blocking and will not return until the operation has completed across all concerned EM cores. Sync-API calls can block the core for a long (indefinite) time, thus they should not be used to make runtime changes on real time EM cores - consider the async variants of the APIs in these cases instead. While one EM-core is calling a sync-API function, the others must be running the EM dispatch loop to be able to receive and handle the sync-API request events sent internally. Use the sync-APIs mainly to simplify application start-up or teardown.

The EO's global start function can be called on any core type, i.e. also on EM_CORE_TYPE_EXTERNAL if em_eo_start_sync() is called from there.

Parameters

	eo	EO handle
[out]	result	Optional pointer to em_status_t, which gets updated to the return value of the actual user provided EO global start function.
	conf	Optional startup configuration, NULL ok.

Returns: EM_OK if successful.

See also: em_start_func_t(), em_start_local_func_t(), em_eo_stop(); em_eo_start() for an asynchronous version of the API

Definition at line 915 of file event_machine_eo.c.

◆ em_eo_state()

em_eo_state_t em_eo_state ( em_eo_t eo )

Return the Execution Object (EO) state.

Returns the current state of the given EO.

Returns: The current EO state or EM_EO_STATE_UNDEF if never created.

Examples: queue_types_ag.c.

Definition at line 1205 of file event_machine_eo.c.

◆ em_eo_stop()

em_status_t em_eo_stop	(	em_eo_t	eo,
		int	num_notif,
		const em_notif_t	notif_tbl[]
	)

Stop Execution Object (EO), asynchronous (non-blocking)

Disables event dispatch from all related queues, calls core local stop on all cores and finally calls the global stop function of the EO when all cores have returned from the (optional) core local stop. The call to the global EO stop is asynchronous and only done when all cores have completed processing of the receive function and/or core local stop. This guarantees no other core is accessing EO data during the EO global stop function.

The EO's global stop function can be called on any core type, i.e. also on EM_CORE_TYPE_EXTERNAL if em_eo_stop() is called from there.

This function returns immediately, but may only fully complete later. If the caller needs to know when the EO stop has actually completed, the num_notif and notif_tbl should be used. The given notification event(s) will be sent to given queue(s) when the stop operation actually completes. If such notifications are not needed, use '0' as 'num_notif'.

When the EO has stopped it can be started again with em_eo_start().

Parameters

eo	EO handle
num_notif	Number of notification events, 0 for no notification
notif_tbl	Array of pairs of event and queue identifiers (+ optional event groups to send the events with)

Returns: EM_OK if successful.

See also: em_stop_func_t(), em_stop_local_func_t(), em_eo_start(), em_eo_stop_sync()

Definition at line 1039 of file event_machine_eo.c.

◆ em_eo_stop_sync()

em_status_t em_eo_stop_sync ( em_eo_t eo )

Stop Execution Object (EO), synchronous (blocking)

As em_eo_stop(), but will not return until the operation is complete.

Note that the function is blocking and will not return until the operation has completed across all concerned EM cores. Sync-API calls can block the core for a long (indefinite) time, thus they should not be used to make runtime changes on real time EM cores - consider the async variants of the APIs in these cases instead. While one core is calling a sync-API function, the others must be running the EM dispatch loop to be able to receive and handle the sync-API request events sent internally. Use the sync-APIs mainly to simplify application start-up or teardown.

The EO's global stop function can be called on any core type, i.e. also on EM_CORE_TYPE_EXTERNAL if em_eo_stop_sync() is called from there.

Parameters

eo EO handle

Returns: EM_OK if successful.

See also: em_stop_func_t(), em_stop_local_func_t(), em_eo_start(); em_eo_stop() for an asynchronous version of the API

Definition at line 1097 of file event_machine_eo.c.

◆ em_eo_to_u64()

uint64_t em_eo_to_u64 ( em_eo_t eo )

Convert an Execution Object (EO) handle to an unsigned integer

Parameters

eo	EO 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_eo_t handle.

Definition at line 1332 of file event_machine_eo.c.

◆ em_eo_unregister_error_handler()

em_status_t em_eo_unregister_error_handler ( em_eo_t eo )

Unregister an Execution Object (EO) specific error handler.

Removes a previously registered EO specific error handler and restores the global error handler into use for the EO.

Parameters

eo EO handle

Returns: EM_OK if successful.

Examples: error.c.

Definition at line 766 of file event_machine_eo.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ em_eo_get_context

◆ em_eo_get_first

◆ em_eo_get_name

◆ em_eo_get_next

◆ em_eo_get_state

◆ em_eo_queue_get_first

◆ em_eo_queue_get_next

Typedef Documentation

◆ em_receive_func_t

◆ em_receive_multi_func_t

◆ em_start_func_t

◆ em_start_local_func_t

◆ em_stop_func_t

◆ em_stop_local_func_t

Enumeration Type Documentation

◆ em_eo_start_local_mode_t

◆ em_eo_state_t

◆ em_eo_stop_local_mode_t

Function Documentation

◆ em_eo_add_queue()

◆ em_eo_add_queue_sync()

◆ em_eo_context()

◆ em_eo_create()

◆ em_eo_create_multircv()

◆ em_eo_create_param()

◆ em_eo_current()

◆ em_eo_delete()

◆ em_eo_find()

◆ em_eo_first()

◆ em_eo_multircv_param_init()

◆ em_eo_name()

◆ em_eo_next()

◆ em_eo_param_init()

◆ em_eo_queue_first()

◆ em_eo_queue_next()

◆ em_eo_register_error_handler()

◆ em_eo_remove_queue()

◆ em_eo_remove_queue_all()

◆ em_eo_remove_queue_all_sync()

◆ em_eo_remove_queue_sync()

◆ em_eo_start()

◆ em_eo_start_sync()

◆ em_eo_state()

◆ em_eo_stop()

◆ em_eo_stop_sync()

◆ em_eo_to_u64()

◆ em_eo_unregister_error_handler()