main_executor.hpp File Reference

Executor for the application's main queue. More...

#include <stlab/execution/config.hpp>
#include <stlab/concurrency/default_executor.hpp>
#include <stlab/concurrency/task.hpp>
#include <type_traits>
#include <utility>

Go to the source code of this file.

Functions
void	stlab::stlab_v2_main_executor_submit (const unsigned char *task_abi_guard, const stlab_v2_task_concept *vtable, stlab_v2_task_proc invoke, void *source) noexcept
	Submits one task to the main queue.
void	stlab::stlab_v2_main_executor_run ()
	Keeps the main queue serviced; never returns.
void	stlab::main_executor_run ()
	Keeps the main queue serviced; never returns.

Variables
constexpr auto	stlab::main_executor
	Runs void() noexcept tasks on the configured main queue in submission order, except that cooperative retirement prioritizes main work posted by draining producers. Remains available after pre_exit() so a final queued task can terminate the process.

Detailed Description

Executor for the application's main queue.

Tasks submitted to main_executor normally run in submission order on the main queue selected by STLAB_MAIN_EXECUTOR when stlab-execution is configured: the libdispatch main queue, the Qt application event loop, the Emscripten main runtime thread, or (opt-in) a portable stlab-owned queue. On native platforms, main_executor_run() services the main queue on the calling thread and never returns, like dispatch_main(). The main queue remains available after pre_exit(). A shutdown task can call pre_exit() to retire timer/default-executor producers, then post another main task that calls std::exit(). That exit task follows main work submitted by the retired producers, but does not drain work that earlier main tasks subsequently enqueue. Producers being joined must not synchronously depend on main-queue progress while the main thread is inside pre_exit().

On Emscripten, the runtime event loop may service main tasks before main_executor_run(), including while main() runs on a proxied pthread. main_executor_run() keeps that runtime alive without returning. The final main task schedules a separate emscripten_async_call() callback, returns normally, and calls emscripten_force_exit() from that callback; link the executable with -sEXIT_RUNTIME=1 for it to terminate.

Threadless Emscripten shutdown is an asynchronous barrier: default/high/low tasks drain before ordinary main dispatch resumes. Main submissions by draining executor callbacks, their capture destructors, and the remaining pre-exit handlers precede ordinary main submissions deferred by that barrier. FIFO order is preserved within each stream and normal merged submission order is unchanged outside retirement.

Windows has no process main queue (each UI thread owns its message queue), so no main executor is provided there unless STLAB_MAIN_EXECUTOR selects Qt or portable.

Queued targets must meet the lifecycle requirement in task.hpp: construction and moved-from destruction must not submit work. Task bodies and executed-target cleanup may submit additional work.