EM-ODP  3.7.0
Event Machine on ODP
event_machine_dispatcher.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2015-2023, Nokia Solutions and Networks
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * * Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  * * Redistributions in binary form must reproduce the above copyright
12  * notice, this list of conditions and the following disclaimer in the
13  * documentation and/or other materials provided with the distribution.
14  * * Neither the name of the copyright holder nor the names of its
15  * contributors may be used to endorse or promote products derived
16  * from this software without specific prior written permission.
17  *
18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29  */
30 
31 #ifndef EVENT_MACHINE_DISPATCHER_H_
32 #define EVENT_MACHINE_DISPATCHER_H_
33 
34 #pragma GCC visibility push(default)
35 
36 /**
37  * @file
38  * @defgroup em_dispatcher Dispatcher
39  * Event Machine dispatcher related services.
40  * @{
41  *
42  * The EM dispatcher contains the main loop of processing on each EM-core and
43  * interfaces with the scheduler to obtain events for processing.
44  * Further, the EM dispatcher is responsible for passing the events received
45  * on a core, from the scheduler, to the correct EO-receive function along with
46  * information about which queue the events originated from, what their types
47  * are etc.
48  *
49  * EM provides APIs to register, or unregister, dispatch callback hooks, i.e.
50  * user provided callback functions that will be run just before EM calls the
51  * EO-receive function or after returning from it. These callbacks are referred
52  * to as enter- and exit-callbacks respectively.
53  * The dispatch callbacks can be used to collect debug information, statistics
54  * or implement new functionality. The enter-callback is called before entering
55  * the EO-receive function on each core separately. The callback gets all the
56  * same arguments as the EO-receive function and can additionally modify them.
57  * The exit-callback works in a similar way, but is instead called after the
58  * EO-receive function returns and has no arguments except for the EO handle.
59  * Multiple callbacks can be registered. The calling order of multiple
60  * registered functions is the order of registration. If the same function is
61  * registered twice then it will be called twice. The max amount of simultaneous
62  * callbacks is set by the define 'EM_CALLBACKS_MAX'.
63  * If an enter-callback changes the event handle to UNDEF, the next callback
64  * will still be called with event as UNDEF, but the EO-receive function won't
65  * be called with an UNDEF event.
66  */
67 
68 #ifdef __cplusplus
69 extern "C" {
70 #endif
71 
74 
75 /**
76  * @brief EM dispatch duration selection flags
77  *
78  * Combining (bitwise OR) several DURATION flags will instruct the EM dispatcher
79  * to dispatch until the first 'duration' condition is met, whichever happens
80  * first.
81  */
82 typedef enum {
83  /** Select: dispatch forever, never return */
85  /** Select: dispatch until em_dispatch_opt_t::duration.rounds reached */
87  /** Select: dispatch until em_dispatch_opt_t::duration.ns reached */
89  /** Select: dispatch until em_dispatch_opt_t::duration.events reached */
91 
92  /** Select: dispatch until em_dispatch_opt_t::duration.no_events.rounds reached */
94  /** Select: dispatch until em_dispatch_opt_t::duration.no_events.ns reached */
96 
97  /* Keep last, for error checking */
98  EM_DISPATCH_DURATION_LAST
100 
101 /**
102  * Dispatch duration.
103  *
104  * Select which dispatch duration, or combination, is to be used with the
105  * em_dispatch_duration() function.
106  * Bitwise OR .select-flags for a combination.
107  * Dispatch will end when one of the selected 'duration' options is
108  * reached, whichever is hit first.
109  */
110 typedef struct {
111  /**
112  * Select which 'duration'-fields that should be taken into account
113  * when evaluating the em_dispatch_duration() run time.
114  *
115  * Only the duration fields that correspond to set .select-flags
116  * will be used.
117  */
119 
120  /*
121  * Duration fields / values below considered according to .select-flags:
122  */
123 
124  /**
125  * Dispatch for the given number of rounds, if used must be > 0.
126  * Only considered if .select contains EM_DISPATCH_DURATION_ROUNDS.
127  */
128  uint64_t rounds;
129 
130  /**
131  * Dispatch (at least) for the given time in nanoseconds,
132  * if used must be > 0.
133  * Only considered if .select contains EM_DISPATCH_DURATION_NS.
134  *
135  * Using a large value for the option 'wait_ns' relative to .ns
136  * might delay the return from dispatch.
137  *
138  * The runtime of the EO-receive function for the last batch of events
139  * is not covered by .ns.
140  * EM will request new events to dispatch while the
141  * elapsed dispatch time is < .ns.
142  */
143  uint64_t ns;
144 
145  /**
146  * Dispatch until (at least) the given number of events have been
147  * handled, if used must be > 0.
148  * Only considered if .select contains EM_DISPATCH_DURATION_EVENTS.
149  *
150  * Note that the option 'burst_size' affects the number of events
151  * dispatched. EM will request new events to dispatch while the number
152  * of dispatched events is < .events and then handle the whole burst.
153  *
154  * The option 'sched_pause=true' might also increase the number of
155  * events dispatched since the EM dispatcher needs to fetch and handle
156  * any leftover events held locally by the scheduler before returning.
157  */
158  uint64_t events;
159 
160  struct {
161  /**
162  * Dispatch until no events have been received for the
163  * given number of rounds, if used must be > 0.
164  * Only considered if .select contains
165  * EM_DISPATCH_DURATION_NO_EVENTS_ROUNDS.
166  */
167  uint64_t rounds;
168 
169  /**
170  * Dispatch until no events have been received for the
171  * given time in nanoseconds, if used must be > 0.
172  * Only considered if .select contains
173  * EM_DISPATCH_DURATION_NO_EVENTS_NS.
174  */
175  uint64_t ns;
176  } no_events;
178 
179 /**
180  * @brief EM dispatch options
181  *
182  * The options must be initialized once with em_dispatch_opt_init() before
183  * using them with other em_dispatch_...() calls for the first time. Further
184  * calls to em_dispatch_...() with the same options structure do not need
185  * initialization and the user is allowed to modify the options between calls
186  * to change the dispatch behaviour.
187  *
188  * @see em_dispatch_opt_init(), em_dispatch_duration() etc.
189  */
190 typedef struct {
191  /**
192  * Scheduler wait-for-events timeout in nanoseconds, might save power.
193  * The scheduler will wait for events, if no immediately available, for
194  * 'wait_ns' nanoseconds per scheduling / dispatch round.
195  *
196  * Note that using a large 'wait_ns' value relative to a
197  * dispatch duration in 'ns' might delay the return from dispatch.
198  *
199  * 0: do not wait for events (default)
200  */
201  uint64_t wait_ns;
202 
203  /**
204  * Scheduler burst size.
205  * The max number of events the dispatcher will request in one burst
206  * from the scheduler.
207  *
208  * default: EM_SCHED_MULTI_MAX_BURST
209  */
210  uint16_t burst_size;
211 
212  /**
213  * Override the possibly configured dispatcher input-polling callback
214  * (set via em_conf_t::input.input_poll_fn).
215  *
216  * false: Do not skip the input-poll callback if configured (default).
217  * true: Skip the input-poll callback in the dispatcher.
218  */
219  bool skip_input_poll; /* override em_conf_t configuration */
220 
221  /**
222  * Override the possibly configured dispatcher output-drain callback
223  * (set via em_conf_t::output.output_drain_fn).
224  *
225  * false: Do not skip the output-drain callback if configured (default).
226  * true: Skip the output-drain callback in the dispatcher.
227  */
228  bool skip_output_drain; /* override em_conf_t configuration */
229 
230  /**
231  * Pause the scheduler on the calling core when exiting the EM dispatch
232  * function. If enabled, will also resume the scheduling when entering
233  * dispatch. Pausing also implicitly causes the dispatcher to fetch and
234  * handle any leftover events held locally by the scheduler before
235  * returning.
236  *
237  * false: Do not pause and resume the scheduler when entering and
238  * exiting dispatch (default).
239  * true: Pause scheduling when exiting dispatch and resume scheduling
240  * when entering. EM will further empty and dispatch any remaining
241  * events locally stashed in the scheduler before returning
242  * causing some extra dispatch 'rounds' to be run.
243  */
245 
246  /**
247  * Internal check - don't touch!
248  *
249  * EM will verify that em_dispatch_opt_init(opt) has been called
250  * before use with dispatch functions.
251  */
254 
255 /**
256  * @brief Dispatch results
257  *
258  * Output struct for returning the results of the em_dispatch_...() functions
259  * in. Usage of 'em_dispatch_results_t *results' with dispatch functions is
260  * optional and 'NULL' can be used if not interested in the results.
261  */
262 typedef struct {
263  /**
264  * The number of dispatch rounds that were run.
265  */
266  uint64_t rounds;
267 
268  /**
269  * The time in nanoseconds that dispatch was run.
270  * Only filled if requesting EM to dispatch for a certain amount of
271  * time, i.e. if EM_DISPATCH_DURATION_NS or
272  * EM_DISPATCH_DURATION_NO_EVENTS_NS duration selection flags were set
273  * in em_dispatch_duration_t::select when using em_dispatch_duration().
274  * Also set when used with em_dispatch_ns().
275  */
276  uint64_t ns;
277 
278  /**
279  * The number of events that were dispatched.
280  */
281  uint64_t events;
283 
284 /**
285  * @brief Initialize the EM dispatch options.
286  *
287  * The options passed to em_dispatch_...() need to be initialized once before
288  * first use. Further calls to em_dispatch_...() with the same options structure
289  * do not need initialization and the user is allowed to modify the options
290  * between calls to change dispatch behaviour.
291  *
292  * This function may be called before em_init() or em_init_core() since it only
293  * sets the default values for the 'em_dispatch_opt_t *opt' argument.
294  *
295  * @param opt
296  */
298 
299 /**
300  * @brief Run the EM dispatcher for a certain duration with options.
301  *
302  * Called by an EM-core to dispatch (with options) events for EM processing.
303  * The EM dispatcher internally queries the scheduler for events for the
304  * calling EM-core and then dispatches them for processing, i.e. passes the
305  * events to the application EO's receive-function based on the queue the events
306  * were received / dequeued from.
307  *
308  * Combining (bitwise OR) several DURATION selection flags
309  * (see em_dispatch_duration_select_t) will dispatch until the first
310  * duration-condition is met, whichever happens first.
311  *
312  * Example usage:
313  * @code
314  * em_dispatch_duration_t duration;
315  * em_dispatch_opt_t opt;
316  * em_dispatch_results_t results;
317  * em_status_t status;
318  *
319  * em_dispatch_opt_init(&opt); // Mandatory once before first use!
320  * opt.wait_ns = 10000; // Wait max 10 us for events from scheduler
321  * opt.sched_pause = false; // Don't pause scheduling on return
322  *
323  * // Dispatch for 1000 rounds, 200 us or until 300 events have been
324  * // handled. Return when the first of these conditions is met.
325  * duration.select = EM_DISPATCH_DURATION_ROUNDS |
326  * EM_DISPATCH_DURATION_NS |
327  * EM_DISPATCH_DURATION_EVENTS;
328  * duration.rounds = 1000;
329  * duration.ns = 200000; // 200 us
330  * duration.events = 300;
331  * ...
332  * do {
333  // Dispatch until '.rounds' or '.ns' or '.events' reached
334  * status = em_dispatch_duration(&duration, &opt, &results);
335  * ...
336  * // Update 'duration' and 'opt' based on 'results'
337  * // and/or runtime conditions
338  * } while (do_dispatch(&results, ...));
339  *
340  * // Prepare to leave EM dispatching
341  * duration.select = EM_DISPATCH_DURATION_NO_EVENTS_NS;
342  * duration.no_events.ns = 100000;
343  * opt.wait_ns = 0; // No waiting for events
344  * opt.skip_input_poll = true; // No callbacks
345  * opt.skip_output_drain = true; // -"-
346  * opt.sched_pause = true; // Pause scheduling on this EM-core
347  *
348  * status = em_dispatch_duration(&duration, &opt, &results);
349  * // Leave EM dispatching for a while
350  * @endcode
351  *
352  * @param duration Dispatch duration.
353  * @param opt Dispatch options (optional, can be NULL).
354  * If used, must have been initialized with
355  * em_dispatch_opt_init(). One initialization is enough,
356  * later calls to em_dispatch_...(...opt) can reuse (the
357  * possibly modified) 'opt'.
358  * Using NULL is the same as passing 'opt' initialized
359  * with em_dispatch_opt_init(&opt) without further changes.
360  * @param[out] results Dispatch results (optional, can be NULL).
361  * Filled for successful dispatch scenarios, i.e. when the
362  * return value is EM_OK.
363  *
364  * @return Error status code
365  * @retval EM_OK when dispatch was successful, 'result' is filled (if provided)
366  * @retval other than EM_OK on error, 'result' is untouched
367  */
369  const em_dispatch_opt_t *opt,
370  em_dispatch_results_t *results /*out*/);
371 /**
372  * @brief Run the EM dispatcher for a given amount of time (in nanoseconds).
373  *
374  * Similar to em_dispatch_duration(), but with a simplified dispatch duration:
375  * here only the number of nanoseconds to dispatch is provided.
376  *
377  * Using a large value for 'opt.wait_ns' relative to 'ns' might delay the
378  * return from dispatch.
379  *
380  * The runtime of the EO-receive function for the last batch of events
381  * is not covered by 'ns'.
382  * EM will request new events to dispatch while the elapsed time is < 'ns'.
383  *
384  * @see em_dispatch_duration() for documentation and usage.
385  *
386  * @param ns Dispatch duration in nanoseconds.
387  * Note that 'ns=0' is not allowed!
388  * @param opt Dispatch options (optional, can be NULL).
389  * If used, must have been initialized with
390  * em_dispatch_opt_init(). One initialization is enough,
391  * later calls to em_dispatch_...(...opt) can reuse (the
392  * possibly modified) 'opt'.
393  * Using NULL is the same as passing 'opt' initialized
394  * with em_dispatch_opt_init(&opt) without further changes.
395  * @param[out] results Dispatch results (optional, can be NULL).
396  * Filled for successful dispatch scenarios, i.e. when the
397  * return value is EM_OK.
398  *
399  * @return Error status code
400  * @retval EM_OK when dispatch was successful, 'result' is filled (if provided)
401  * @retval other than EM_OK on error, 'result' is untouched
402  */
403 em_status_t em_dispatch_ns(uint64_t ns,
404  const em_dispatch_opt_t *opt,
405  em_dispatch_results_t *results /*out*/);
406 
407 /**
408  * @brief Run the EM dispatcher until a given number of events have been
409  * dispatched.
410  *
411  * Similar to em_dispatch_duration(), but with a simplified dispatch duration:
412  * here only the number of events to dispatch is provided.
413  *
414  * Note that 'opt.burst_size' affects the number of events dispatched.
415  * EM will request new events to dispatch while the number of dispatched
416  * events is < .events and then handle the whole burst.
417  *
418  * The option 'opt.sched_pause=true' might also increase the number of
419  * events dispatched since the EM dispatcher needs to fetch and handle
420  * any leftover events held locally by the scheduler before returning.
421  *
422  * @see em_dispatch_duration() for documentation and usage.
423  *
424  * @param events Dispatch duration events. Dispatch until the given
425  * number of events have been dispatched.
426  * Note that 'events=0' is not allowed!
427  * @param opt Dispatch options (optional, can be NULL).
428  * If used, must have been initialized with
429  * em_dispatch_opt_init(). One initialization is enough,
430  * later calls to em_dispatch_...(...opt) can reuse (the
431  * possibly modified) 'opt'.
432  * Using NULL is the same as passing 'opt' initialized
433  * with em_dispatch_opt_init(&opt) without further changes.
434  * @param[out] results Dispatch results (optional, can be NULL).
435  * Filled for successful dispatch scenarios, i.e. when the
436  * return value is EM_OK.
437  *
438  * @return Error status code
439  * @retval EM_OK when dispatch was successful, 'result' is filled (if provided)
440  * @retval other than EM_OK on error, 'result' is untouched
441  */
442 em_status_t em_dispatch_events(uint64_t events,
443  const em_dispatch_opt_t *opt,
444  em_dispatch_results_t *results /*out*/);
445 
446 /**
447  * @brief Run the EM dispatcher for a given number of dispatch-rounds.
448  *
449  * Similar to em_dispatch_duration(), but with a simplified dispatch duration:
450  * here only the number of rounds to dispatch is provided.
451  *
452  * @see em_dispatch_duration() for documentation and usage.
453  *
454  * @param rounds Dispatch duration rounds. Dispatch for the given number
455  * of rounds.
456  * Note that 'rounds=0' is not allowed!
457  * @param opt Dispatch options (optional, can be NULL).
458  * If used, must have been initialized with
459  * em_dispatch_opt_init(). One initialization is enough,
460  * later calls to em_dispatch_...(...opt) can reuse (the
461  * possibly modified) 'opt'.
462  * Using NULL is the same as passing 'opt' initialized
463  * with em_dispatch_opt_init(&opt) without further changes.
464  * @param[out] results Dispatch results (optional, can be NULL).
465  * Filled for successful dispatch scenarios, i.e. when the
466  * return value is EM_OK.
467  *
468  * @return Error status code
469  * @retval EM_OK when dispatch was successful, 'result' is filled (if provided)
470  * @retval other than EM_OK on error, 'result' is untouched
471  */
472 em_status_t em_dispatch_rounds(uint64_t rounds,
473  const em_dispatch_opt_t *opt,
474  em_dispatch_results_t *results /*out*/);
475 
476 /**
477  * EM event dispatch
478  *
479  * Called by an EM-core to dispatch events for EM processing.
480  * The EM dispatcher internally queries the scheduler for events for the
481  * calling EM-core and then dispatches them for processing, i.e. passes the
482  * events to the application EO's receive-function based on the queue the events
483  * were received / dequeued from.
484  *
485  * See the EM config file for options controlling the global behaviour of
486  * em_dispatch().
487  *
488  * @param rounds Dispatch rounds before returning,
489  * 0 means 'never return from dispatch'
490  *
491  * @return The number of events dispatched on this core.
492  * Only makes sense if 'rounds > 0'
493  *
494  * @see em_dispatch_duration() for a function that enables dispatching
495  * with more options.
496  */
497 uint64_t em_dispatch(uint64_t rounds);
498 
499 /**
500  * Dispatcher global EO-receive enter-callback.
501  *
502  * Common dispatch callback run before EO-receive functions of both the
503  * em_receive_func_t and em_receive_multi_func_t types (i.e. for EOs created
504  * with either em_eo_create() or em_eo_create_multircv()).
505  *
506  * Enter-callbacks are run just before entering EO-receive functions, they can
507  * be useful for debugging, collecting statistics, manipulating events before
508  * they reach the EO or implementing new services needing synchronization
509  * between cores.
510  * Arguments common for both types of EO receive functions are passed as
511  * references to the enter-callback (the event-type passed to the single-event
512  * receive function case is not passed, use em_event_get/set_type() instead).
513  * Arguments are references, i.e. the callback can optionally modify them.
514  * If modified, the new values will go to the next callback and eventually to
515  * the multi-event EO-receive function.
516  *
517  * Events can be dropped by changing the event-entries in the events[num]-array
518  * to EM_EVENT_UNDEF. Neither EO-receive nor any further enter-callbacks will
519  * be called if all events have been dropped by the callbacks already run, i.e.
520  * no callback will be called with 'num=0'.
521  * The callback itself needs to handle the events it drops, e.g. free them.
522  * Note: EM will remove entries of EM_EVENT_UNDEF from the events[]-array before
523  * calling the next enter-callback (if several registered) or the
524  * receive function and adjust 'num' accordingly for the call.
525  *
526  * The EO handle can be used to separate callback functionality per EO and the
527  * core id can be obtained for core specific functionality.
528  *
529  * Callback functions can be called concurrently from different cores.
530  *
531  * @see em_dispatch_register_enter_cb()
532  */
533 typedef void (*em_dispatch_enter_func_t)(em_eo_t eo, void **eo_ctx,
534  em_event_t events[/*in/out*/], int num,
535  em_queue_t *queue, void **q_ctx);
536 
537 /**
538  * Dispatcher global EO-receive exit-callback.
539  *
540  * The exit-callbacks are run after EO-receive returns.
541  * Some arguments given to EO-receive might not be valid afterwards, thus
542  * the only argument given to the exit callback is the EO handle.
543  *
544  * Callback functions can be called concurrently from different cores.
545  *
546  * @see em_dispatch_register_exit_cb()
547  */
548 typedef void (*em_dispatch_exit_func_t)(em_eo_t eo);
549 
550 /**
551  * Register an EO-enter callback
552  *
553  * Register a global function to be called by the dispatcher just before calling
554  * an EO-receive function. This can be useful for debugging, collecting
555  * statistics, manipulating events before they reach the EO or implementing new
556  * services needing synchronization between cores.
557  *
558  * The function registered should be kept short since it will be run each time
559  * just before calling EO-receive. All registered callbacks will further
560  * increase the processing time.
561  *
562  * Multiple callbacks can be registered.
563  * The order of calling multiple registered functions is the order of
564  * registration. If same function is registered twice it will be called twice.
565  * The maximum number of simultaneous callbacks is system specific
566  * (EM_CALLBACKS_MAX).
567  *
568  * @param func Callback function
569  *
570  * @return EM_OK if callback registration succeeded
571  *
572  * @see em_dispatch_enter_func_t
573  */
576 
577 /**
578  * Unregister an EO-enter callback
579  *
580  * This can be used to unregister a previously registered enter-function.
581  *
582  * The given function is searched for and if found removed from the call list.
583  * If the same function has been registered multiple times, only one reference
584  * is removed per unregister call.
585  * Note that when this function returns, no new calls are made to the removed
586  * callback function, but it is still possible that another core could be
587  * executing the function, so care must be taken before removing anything it may
588  * still use.
589  *
590  * @param func Callback function
591  *
592  * @return EM_OK if the given function was found and removed.
593  */
596 
597 /**
598  * Register an EO-exit callback
599  *
600  * Register a global function to be called by the dispatcher just after return
601  * from an EO-receive function.
602  *
603  * The function registered should be kept short since it will be run each time
604  * just after EO-receive returns. All registered callbacks will further increase
605  * the processing time.
606  *
607  * Multiple callbacks can be registered.
608  * The order of calling multiple registered functions is the order of
609  * registration. If same function is registered twice it will be called twice.
610  * The maximum number of simultaneous callbacks is system specific
611  * (EM_CALLBACKS_MAX).
612  *
613  * @param func Callback function
614  *
615  * @return EM_OK if callback registration succeeded
616  *
617  * @see em_dispatch_register_enter_cb(), em_dispatch_unregister_exit_cb()
618  */
621 
622 /**
623  * Unregister an EO-exit callback
624  *
625  * This can be used to unregister a previously registered exit-function.
626  *
627  * Given function pointer is searched and if found removed from the call list.
628  * If one function is registered multiple times only one reference is removed.
629  *
630  * The given function is searched for and if found removed from the call list.
631  * If the same function has been registered multiple times, only one reference
632  * is removed per unregister call.
633  * Note that when this function returns, no new calls are made to the removed
634  * callback function, but it is still possible that another core could be
635  * executing the function, so care must be taken before removing anything it may
636  * still use.
637  *
638  * @param func Callback function
639  *
640  * @return EM_OK if the given function was found and removed.
641  *
642  * @see em_dispatch_exit_func_t
643  */
646 
647 /**
648  * @}
649  */
650 #ifdef __cplusplus
651 }
652 #endif
653 
654 #pragma GCC visibility pop
655 #endif /* EVENT_MACHINE_DISPATCHER_H_ */
em_dispatch_duration_t::ns
uint64_t ns
Definition: event_machine_dispatcher.h:143
em_dispatch_duration_select_t
em_dispatch_duration_select_t
EM dispatch duration selection flags.
Definition: event_machine_dispatcher.h:82
em_dispatch_duration_t::rounds
uint64_t rounds
Definition: event_machine_dispatcher.h:128
em_dispatch_exit_func_t
void(* em_dispatch_exit_func_t)(em_eo_t eo)
Definition: event_machine_dispatcher.h:548
em_dispatch_duration_t::select
em_dispatch_duration_select_t select
Definition: event_machine_dispatcher.h:118
em_dispatch_results_t::ns
uint64_t ns
Definition: event_machine_dispatcher.h:276
em_dispatch_duration_t
Definition: event_machine_dispatcher.h:110
em_dispatch_results_t::rounds
uint64_t rounds
Definition: event_machine_dispatcher.h:266
em_dispatch_opt_t
EM dispatch options.
Definition: event_machine_dispatcher.h:190
em_dispatch_opt_t::skip_input_poll
bool skip_input_poll
Definition: event_machine_dispatcher.h:219
em_dispatch
uint64_t em_dispatch(uint64_t rounds)
Definition: event_machine_dispatcher.c:40
em_dispatch_opt_t::burst_size
uint16_t burst_size
Definition: event_machine_dispatcher.h:210
em_dispatch_duration_t::events
uint64_t events
Definition: event_machine_dispatcher.h:158
em_dispatch_rounds
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.
Definition: event_machine_dispatcher.c:243
EM_DISPATCH_DURATION_NS
@ EM_DISPATCH_DURATION_NS
Definition: event_machine_dispatcher.h:88
em_dispatch_ns
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).
Definition: event_machine_dispatcher.c:183
em_dispatch_register_enter_cb
em_status_t em_dispatch_register_enter_cb(em_dispatch_enter_func_t func)
Definition: event_machine_dispatcher.c:274
EM_DISPATCH_DURATION_FOREVER
@ EM_DISPATCH_DURATION_FOREVER
Definition: event_machine_dispatcher.h:84
em_dispatch_opt_t::sched_pause
bool sched_pause
Definition: event_machine_dispatcher.h:244
em_dispatch_opt_t::skip_output_drain
bool skip_output_drain
Definition: event_machine_dispatcher.h:228
em_dispatch_results_t
Dispatch results.
Definition: event_machine_dispatcher.h:262
em_dispatch_duration
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.
Definition: event_machine_dispatcher.c:136
em_dispatch_results_t::events
uint64_t events
Definition: event_machine_dispatcher.h:281
em_status_t
uint32_t em_status_t
Definition: event_machine_types.h:321
EM_DISPATCH_DURATION_EVENTS
@ EM_DISPATCH_DURATION_EVENTS
Definition: event_machine_dispatcher.h:90
em_dispatch_opt_t::wait_ns
uint64_t wait_ns
Definition: event_machine_dispatcher.h:201
event_machine_hw_types.h
em_dispatch_opt_t::__internal_check
uint32_t __internal_check
Definition: event_machine_dispatcher.h:252
EM_DISPATCH_DURATION_NO_EVENTS_ROUNDS
@ EM_DISPATCH_DURATION_NO_EVENTS_ROUNDS
Definition: event_machine_dispatcher.h:93
em_dispatch_opt_init
void em_dispatch_opt_init(em_dispatch_opt_t *opt)
Initialize the EM dispatch options.
Definition: event_machine_dispatcher.c:77
EM_DISPATCH_DURATION_ROUNDS
@ EM_DISPATCH_DURATION_ROUNDS
Definition: event_machine_dispatcher.h:86
em_dispatch_enter_func_t
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)
Definition: event_machine_dispatcher.h:533
event_machine_types.h
em_dispatch_unregister_enter_cb
em_status_t em_dispatch_unregister_enter_cb(em_dispatch_enter_func_t func)
Definition: event_machine_dispatcher.c:293
em_dispatch_unregister_exit_cb
em_status_t em_dispatch_unregister_exit_cb(em_dispatch_exit_func_t func)
Definition: event_machine_dispatcher.c:330
em_dispatch_events
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.
Definition: event_machine_dispatcher.c:213
em_dispatch_register_exit_cb
em_status_t em_dispatch_register_exit_cb(em_dispatch_exit_func_t func)
Definition: event_machine_dispatcher.c:312
EM_DISPATCH_DURATION_NO_EVENTS_NS
@ EM_DISPATCH_DURATION_NO_EVENTS_NS
Definition: event_machine_dispatcher.h:95