 |
EM-ODP
3.8.0-1
Event Machine on ODP
|
|
EM-ODP
3.8.0-1
Event Machine on ODP
|
Data Structures | |
| struct | em_dispatch_duration_t |
| struct | em_dispatch_opt_t |
| EM dispatch options. More... | |
| struct | em_dispatch_results_t |
| Dispatch results. More... | |
Typedefs | |
| typedef void(* | em_dispatch_enter_func_t) (em_eo_t eo, void **eo_ctx, em_event_t events[], int num, em_queue_t *queue, void **q_ctx) |
| typedef void(* | em_dispatch_exit_func_t) (em_eo_t eo) |
Enumerations | |
| enum | em_dispatch_duration_select_t { EM_DISPATCH_DURATION_FOREVER = 0 , EM_DISPATCH_DURATION_ROUNDS = 1 , EM_DISPATCH_DURATION_NS = 2 , EM_DISPATCH_DURATION_EVENTS = 4 , EM_DISPATCH_DURATION_NO_EVENTS_ROUNDS = 8 , EM_DISPATCH_DURATION_NO_EVENTS_NS = 16 , EM_DISPATCH_DURATION_LAST } |
| EM dispatch duration selection flags. More... | |
Event Machine dispatcher related services.
The EM dispatcher contains the main loop of processing on each EM-core and interfaces with the scheduler to obtain events for processing. Further, the EM dispatcher is responsible for passing the events received on a core, from the scheduler, to the correct EO-receive function along with information about which queue the events originated from, what their types are etc. Different flavours of the EM dispatch APIs exist along with configuration options.
EM provides APIs to register, or unregister, dispatch callback hooks, i.e. user provided callback functions that will be run just before EM calls the EO-receive function or after returning from it. These callbacks are referred to as dispatch enter- and exit-callbacks respectively. The dispatch callbacks can be used to collect debug information, statistics or implement new functionality.
The dispatch enter-callbacks are called before entering the EO-receive function on each EM-core separately. Events can be dropped by an enter- callback. Neither the EO-receive function nor any further enter-callbacks will be called if all events have been dropped by the callbacks already run. The callback itself needs to handle the events it drops, e.g. free them.
The dispatch exit-callbacks are called after the EO-receive function returns and have no arguments except for the EO handle. Note that all exit-callbacks are always called (even if the enter-callbacks dropped the events causing the rest of the enter-callbacks and the EO-receive function to be skipped).
Multiple callbacks can be registered. The calling order of multiple registered callbacks is the order of registration. If the same function is registered twice then it will be called twice. The max amount of simultaneous callbacks is set by the define 'EM_CALLBACKS_MAX'.
EM does not know of any connection or relationship between registered dispatch enter- and/or exit-callbacks. All dispatch callbacks are treated as independent entries. Functionality that e.g. depends on both an enter- and an exit-callback being run must take into acconut that the previous enter-callbacks might have dropped all events, thus skipping the following enter-callbacks - but still running all exit-callbacks.
| typedef void(* em_dispatch_enter_func_t) (em_eo_t eo, void **eo_ctx, em_event_t events[], int num, em_queue_t *queue, void **q_ctx) |
Dispatch enter-callback.
Common dispatch callback run before EO-receive functions of both the em_receive_func_t and em_receive_multi_func_t types (i.e. for EOs created with either em_eo_create() or em_eo_create_multircv()).
Enter-callbacks are run just before entering EO-receive functions, they can be useful for debugging, collecting statistics, manipulating events before they reach the EO or implementing new services needing synchronization between cores. Some of the arguments common for both types of EO receive functions are passed as pointers to the enter-callback so that the callback can optionally modify them. If modified, the new values will go to the next callback and eventually to the EO-receive function.
Events can be dropped by changing the event-entries in the events[num]-array to EM_EVENT_UNDEF. Neither EO-receive nor any further enter-callbacks will be called if all events have been dropped by the callbacks already run, i.e. no callback will be called with 'num=0'. The callback itself needs to handle the events it drops, e.g. free them. Note: EM will remove entries of EM_EVENT_UNDEF from the events[]-array before calling the next enter-callback (if several registered) or the receive function and adjust 'num' accordingly for the call.
Functionality that e.g. depends on both an enter- and an exit-callback being run must take into acconut that the previous enter-callbacks might have dropped all events, thus skipping the following enter-callbacks - but still running all exit-callbacks.
The EO handle can be used to separate callback functionality per EO and the core id can be obtained for core specific functionality.
Callback functions can be called concurrently from different cores.
Definition at line 549 of file event_machine_dispatcher.h.
| typedef void(* em_dispatch_exit_func_t) (em_eo_t eo) |
Dispatcher exit-callback.
The exit-callbacks are run after EO-receive returns. Some arguments given to EO-receive might not be valid afterwards, thus the only argument given to the exit callback is the EO handle.
Callback functions can be called concurrently from different cores.
Functionality that e.g. depends on both an enter- and an exit-callback being run must take into acconut that the previous enter-callbacks might have dropped all events, thus skipping the following enter-callbacks - but still running all exit-callbacks.
Definition at line 569 of file event_machine_dispatcher.h.
EM dispatch duration selection flags.
Combining (bitwise OR) several DURATION flags will instruct the EM dispatcher to dispatch until the first 'duration' condition is met, whichever happens first.
Definition at line 95 of file event_machine_dispatcher.h.
| uint64_t em_dispatch | ( | uint64_t | rounds | ) |
EM event dispatch
Called by an EM-core to dispatch events for EM processing. The EM dispatcher internally queries the scheduler for events for the calling EM-core and then dispatches them for processing, i.e. passes the events to the application EO's receive-function based on the queue the events were received / dequeued from.
See the EM config file for options controlling the global behaviour of em_dispatch().
| rounds | Dispatch rounds before returning, 0 means 'never return from dispatch' |
Definition at line 40 of file event_machine_dispatcher.c.
| em_status_t em_dispatch_duration | ( | const em_dispatch_duration_t * | duration, |
| const em_dispatch_opt_t * | opt, | ||
| em_dispatch_results_t * | results | ||
| ) |
Run the EM dispatcher for a certain duration with options.
Called by an EM-core to dispatch (with options) events for EM processing. The EM dispatcher internally queries the scheduler for events for the calling EM-core and then dispatches them for processing, i.e. passes the events to the application EO's receive-function based on the queue the events were received / dequeued from.
Combining (bitwise OR) several DURATION selection flags (see em_dispatch_duration_select_t) will dispatch until the first duration-condition is met, whichever happens first.
Example usage:
| duration | Dispatch duration. | |
| opt | Dispatch options (optional, can be NULL). If used, must have been initialized with em_dispatch_opt_init(). One initialization is enough, later calls to em_dispatch_...(...opt) can reuse (the possibly modified) 'opt'. Using NULL is the same as passing 'opt' initialized with em_dispatch_opt_init(&opt) without further changes. | |
| [out] | results | Dispatch results (optional, can be NULL). Filled for successful dispatch scenarios, i.e. when the return value is EM_OK. |
| EM_OK | when dispatch was successful, 'result' is filled (if provided) |
| other | than EM_OK on error, 'result' is untouched |
Definition at line 136 of file event_machine_dispatcher.c.
| em_status_t em_dispatch_events | ( | uint64_t | events, |
| const em_dispatch_opt_t * | opt, | ||
| em_dispatch_results_t * | results | ||
| ) |
Run the EM dispatcher until a given number of events have been dispatched.
Similar to em_dispatch_duration(), but with a simplified dispatch duration: here only the number of events to dispatch is provided.
Note that 'opt.burst_size' affects the number of events dispatched. EM will request new events to dispatch while the number of dispatched events is < .events and then handle the whole burst.
The option 'opt.sched_pause=true' might also increase the number of events dispatched since the EM dispatcher needs to fetch and handle any leftover events held locally by the scheduler before returning.
| events | Dispatch duration events. Dispatch until the given number of events have been dispatched. Note that 'events=0' is not allowed! | |
| opt | Dispatch options (optional, can be NULL). If used, must have been initialized with em_dispatch_opt_init(). One initialization is enough, later calls to em_dispatch_...(...opt) can reuse (the possibly modified) 'opt'. Using NULL is the same as passing 'opt' initialized with em_dispatch_opt_init(&opt) without further changes. | |
| [out] | results | Dispatch results (optional, can be NULL). Filled for successful dispatch scenarios, i.e. when the return value is EM_OK. |
| EM_OK | when dispatch was successful, 'result' is filled (if provided) |
| other | than EM_OK on error, 'result' is untouched |
Definition at line 213 of file event_machine_dispatcher.c.
| em_status_t em_dispatch_ns | ( | uint64_t | ns, |
| const em_dispatch_opt_t * | opt, | ||
| em_dispatch_results_t * | results | ||
| ) |
Run the EM dispatcher for a given amount of time (in nanoseconds).
Similar to em_dispatch_duration(), but with a simplified dispatch duration: here only the number of nanoseconds to dispatch is provided.
Using a large value for 'opt.wait_ns' relative to 'ns' might delay the return from dispatch.
The runtime of the EO-receive function for the last batch of events is not covered by 'ns'. EM will request new events to dispatch while the elapsed time is < 'ns'.
| ns | Dispatch duration in nanoseconds. Note that 'ns=0' is not allowed! | |
| opt | Dispatch options (optional, can be NULL). If used, must have been initialized with em_dispatch_opt_init(). One initialization is enough, later calls to em_dispatch_...(...opt) can reuse (the possibly modified) 'opt'. Using NULL is the same as passing 'opt' initialized with em_dispatch_opt_init(&opt) without further changes. | |
| [out] | results | Dispatch results (optional, can be NULL). Filled for successful dispatch scenarios, i.e. when the return value is EM_OK. |
| EM_OK | when dispatch was successful, 'result' is filled (if provided) |
| other | than EM_OK on error, 'result' is untouched |
Definition at line 183 of file event_machine_dispatcher.c.
| void em_dispatch_opt_init | ( | em_dispatch_opt_t * | opt | ) |
Initialize the EM dispatch options.
The options passed to em_dispatch_...() need to be initialized once before first use. Further calls to em_dispatch_...() with the same options structure do not need initialization and the user is allowed to modify the options between calls to change dispatch behaviour.
This function may be called before em_init() or em_init_core() since it only sets the default values for the 'em_dispatch_opt_t *opt' argument.
| opt |
Definition at line 77 of file event_machine_dispatcher.c.
| em_status_t em_dispatch_register_enter_cb | ( | em_dispatch_enter_func_t | func | ) |
Register a dispatch enter-callback
Register a global function to be called by the dispatcher just before calling an EO-receive function. This can be useful for debugging, collecting statistics, manipulating events before they reach the EO or implementing new services needing synchronization between cores.
The function registered should be kept short since it will be run each time just before calling EO-receive. All registered callbacks will further increase the processing time.
Multiple callbacks can be registered. The order of calling multiple registered functions is the order of registration. If same function is registered twice it will be called twice. The maximum number of simultaneous callbacks is system specific (EM_CALLBACKS_MAX).
| func | Dispatch enter-callback function |
Definition at line 274 of file event_machine_dispatcher.c.
| em_status_t em_dispatch_register_exit_cb | ( | em_dispatch_exit_func_t | func | ) |
Register a dispatch exit-callback
Register a global function to be called by the dispatcher just after return from an EO-receive function.
The function registered should be kept short since it will be run each time just after EO-receive returns. All registered callbacks will further increase the processing time.
Multiple callbacks can be registered. The order of calling multiple registered functions is the order of registration. If same function is registered twice it will be called twice. The maximum number of simultaneous callbacks is system specific (EM_CALLBACKS_MAX).
| func | Dispatch exit-callback function |
Definition at line 312 of file event_machine_dispatcher.c.
| em_status_t em_dispatch_rounds | ( | uint64_t | rounds, |
| const em_dispatch_opt_t * | opt, | ||
| em_dispatch_results_t * | results | ||
| ) |
Run the EM dispatcher for a given number of dispatch-rounds.
Similar to em_dispatch_duration(), but with a simplified dispatch duration: here only the number of rounds to dispatch is provided.
| rounds | Dispatch duration rounds. Dispatch for the given number of rounds. Note that 'rounds=0' is not allowed! | |
| opt | Dispatch options (optional, can be NULL). If used, must have been initialized with em_dispatch_opt_init(). One initialization is enough, later calls to em_dispatch_...(...opt) can reuse (the possibly modified) 'opt'. Using NULL is the same as passing 'opt' initialized with em_dispatch_opt_init(&opt) without further changes. | |
| [out] | results | Dispatch results (optional, can be NULL). Filled for successful dispatch scenarios, i.e. when the return value is EM_OK. |
| EM_OK | when dispatch was successful, 'result' is filled (if provided) |
| other | than EM_OK on error, 'result' is untouched |
Definition at line 243 of file event_machine_dispatcher.c.
| em_status_t em_dispatch_unregister_enter_cb | ( | em_dispatch_enter_func_t | func | ) |
Unregister a dispatch enter-callback
This can be used to unregister a previously registered enter-callback.
The given function is searched for and, if found, removed from the call list. If the same function has been registered multiple times, only one reference is removed per unregister call. Note that when this function returns, no new calls are made to the removed callback function, but it is still possible that another core could be executing the function, so care must be taken before removing anything it may still use.
| func | Dispatch enter-callback function |
Definition at line 293 of file event_machine_dispatcher.c.
| em_status_t em_dispatch_unregister_exit_cb | ( | em_dispatch_exit_func_t | func | ) |
Unregister a dispatch exit-callback
This can be used to unregister a previously registered exit-callback.
The given function is searched for and, if found, removed from the call list. If the same function has been registered multiple times, only one reference is removed per unregister call. Note that when this function returns, no new calls are made to the removed callback function, but it is still possible that another core could be executing the function, so care must be taken before removing anything it may still use.
| func | Dispatch exit-callback function |
Definition at line 330 of file event_machine_dispatcher.c.