 |
EM-ODP
3.7.0
Event Machine on ODP
|
|
EM-ODP
3.7.0
Event Machine on ODP
|
Event Machine dispatcher related services. More...
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.
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 enter- and exit-callbacks respectively. The dispatch callbacks can be used to collect debug information, statistics or implement new functionality. The enter-callback is called before entering the EO-receive function on each core separately. The callback gets all the same arguments as the EO-receive function and can additionally modify them. The exit-callback works in a similar way, but is instead called after the EO-receive function returns and has no arguments except for the EO handle. Multiple callbacks can be registered. The calling order of multiple registered functions 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'. If an enter-callback changes the event handle to UNDEF, the next callback will still be called with event as UNDEF, but the EO-receive function won't be called with an UNDEF event.
| 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) |
Dispatcher global EO-receive 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. Arguments common for both types of EO receive functions are passed as references to the enter-callback (the event-type passed to the single-event receive function case is not passed, use em_event_get/set_type() instead). Arguments are references, i.e. the callback can optionally modify them. If modified, the new values will go to the next callback and eventually to the multi-event 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.
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 533 of file event_machine_dispatcher.h.
| typedef void(* em_dispatch_exit_func_t) (em_eo_t eo) |
Dispatcher global EO-receive 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.
Definition at line 548 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 82 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 an EO-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 | 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 an EO-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 | 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 an EO-enter callback
This can be used to unregister a previously registered enter-function.
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 | 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 an EO-exit callback
This can be used to unregister a previously registered exit-function.
Given function pointer is searched and if found removed from the call list. If one function is registered multiple times only one reference is removed.
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 | Callback function |
Definition at line 330 of file event_machine_dispatcher.c.