A process-wide singleton that drains an event queue across one or more workers. More...
|
Typedefs | |
| typedef void(* | sys_runloop_init_func_t) (uint8_t worker_index) |
| Per-worker initialisation callback. More... | |
| typedef void(* | sys_runloop_event_func_t) (sys_event_t event) |
| Event handler called on a worker for each posted event. More... | |
| typedef void(* | sys_runloop_poll_func_t) (void) |
| Optional periodic poll callback invoked by worker 0. More... | |
| typedef void(* | sys_runloop_exit_func_t) (uint8_t worker_index) |
| Per-worker exit callback. More... | |
Methods | |
| uint32_t | sys_runloop_run (uint8_t num_workers, sys_event_queue_t *queue, sys_runloop_init_func_t init_fn, sys_runloop_event_func_t event_fn, sys_runloop_poll_func_t poll_fn, sys_runloop_exit_func_t exit_fn) |
| Start the run loop and block until shutdown. More... | |
| void | sys_runloop_shutdown (uint32_t exit_value) |
| Signal the run loop to stop accepting events and exit when drained. More... | |
| bool | sys_runloop_post (sys_event_t event) |
| Post an event to be processed by the run loop. More... | |
Detailed Description
A process-wide singleton that drains an event queue across one or more workers.
The run loop is a process-wide singleton that drains an event queue across one or more workers.
Usage model:
- Create an event queue with
sys_event_queue_init()and start the loop withsys_runloop_run(). - Post events from producer contexts using
sys_runloop_post(). - Handle events in the callback supplied to
sys_runloop_run(). - Request shutdown with
sys_runloop_shutdown(exit_value).
Execution semantics:
- The calling thread always acts as worker 0.
- Additional workers are created when
num_workers > 1. - Worker init/exit hooks allow per-worker setup/teardown.
- Shutdown stops new intake, drains queued work, and returns the supplied exit value once workers exit.
Call sys_runloop_run() from the main thread with an event handler; it blocks until sys_runloop_shutdown() is called. Post events from any thread with sys_runloop_post() once the loop is running.
On Pico the calling thread counts as one worker; additional workers are pinned to subsequent cores. On other platforms each additional worker is a new thread.
Typedef Documentation
◆ sys_runloop_event_func_t
| typedef void(* sys_runloop_event_func_t) (sys_event_t event) |
Event handler called on a worker for each posted event.
- Parameters
-
event The event posted via sys_runloop_post().
◆ sys_runloop_exit_func_t
| typedef void(* sys_runloop_exit_func_t) (uint8_t worker_index) |
Per-worker exit callback.
- Parameters
-
worker_index Zero-based index of the worker.
Called once on each worker after the event queue is drained and before the worker exits. Use this to deregister IRQ handlers or release thread-local resources. May be NULL if no cleanup is needed.
◆ sys_runloop_init_func_t
| typedef void(* sys_runloop_init_func_t) (uint8_t worker_index) |
Per-worker initialisation callback.
- Parameters
-
worker_index Zero-based index of the worker (0 = calling thread / core 0, 1 = first additional worker, etc.).
Called once on each worker before it starts draining the event queue. Use this to register IRQ handlers, allocate thread-local resources, or perform any other per-core setup. May be NULL if no initialisation is needed.
◆ sys_runloop_poll_func_t
| typedef void(* sys_runloop_poll_func_t) (void) |
Function Documentation
◆ sys_runloop_post()
| bool sys_runloop_post | ( | sys_event_t | event | ) |
Post an event to be processed by the run loop.
- Parameters
-
event Non-NULL event payload.
- Returns
trueon success,falseif the run loop is shut down or the queue is full.
Safe to call from any thread while the run loop is running. Returns false if called before sys_runloop_run() or after sys_runloop_shutdown(). Events are processed in the order posted.
◆ sys_runloop_run()
| uint32_t sys_runloop_run | ( | uint8_t | num_workers, |
| sys_event_queue_t * | queue, | ||
| sys_runloop_init_func_t | init_fn, | ||
| sys_runloop_event_func_t | event_fn, | ||
| sys_runloop_poll_func_t | poll_fn, | ||
| sys_runloop_exit_func_t | exit_fn | ||
| ) |
Start the run loop and block until shutdown.
- Parameters
-
num_workers Total number of workers, including the calling thread. Pass 0 to use all available cores. Values greater than the number of available cores are clamped to that limit. queue Event queue to use for runloop dispatch. Must be valid; its lifetime remains the caller's responsibility - sys_runloop_run() neither initializes nor deinitializes it. init_fn Called once per worker before it starts. May be NULL.event_fn Handler invoked on a worker for each event dequeued. poll_fn Optional periodic poll callback invoked by worker 0. May be NULL.exit_fn Called once per worker after the queue is drained. May be NULL.
- Returns
- Exit value passed to sys_runloop_shutdown() once all workers have finished draining the queue.
The calling thread becomes worker 0. If num_workers is greater than 1, additional workers (1, 2, …) are started on other cores or threads, each receiving their index in init_fn and exit_fn.
◆ sys_runloop_shutdown()
| void sys_runloop_shutdown | ( | uint32_t | exit_value | ) |
Signal the run loop to stop accepting events and exit when drained.
- Parameters
-
exit_value Value returned by sys_runloop_run() once all workers have exited.
After this call sys_runloop_post() returns false. Workers finish any in-progress and already-queued events, then exit, causing sys_runloop_run() to return exit_value. Safe to call from any thread or event handler. Has no effect if the run loop is not running.