default_executor.hpp File Reference

Thread-pool executors mapping to the OS scheduler (libdispatch, Windows pool, portable). More...

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

Go to the source code of this file.

Typedefs
using	stlab::stlab_v2_task_proc
	Function pointer type submitted through the shared executor ABI.

Functions
void	stlab::stlab_v2_default_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 shared default-priority executor.
void	stlab::stlab_v2_high_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 shared high-priority executor.
void	stlab::stlab_v2_low_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 shared low-priority executor.
void	stlab::stlab_v2_notify_default_executor_before_waiting () noexcept
	Notifies the shared default executor that the calling thread is about to wait.
std::int32_t	stlab::stlab_v2_default_executor_supports_blocking () noexcept
	Returns one when the configured core supports blocking waits, otherwise zero.

Variables
constexpr auto	stlab::low_executor
	Low-priority concurrent executor. Portable executors prioritize queued work without changing OS thread priority; Windows and libdispatch use platform priority hints.
constexpr auto	stlab::default_executor
	Default concurrent executor using the medium-priority queue.
constexpr auto	stlab::high_executor
	High-priority concurrent executor. Portable executors prioritize queued work without changing OS thread priority; Windows and libdispatch use platform priority hints.

Detailed Description

Thread-pool executors mapping to the OS scheduler (libdispatch, Windows pool, portable).

Maps to the OS thread pool when the platform provides one; otherwise uses the library's portable implementation. Common configurations include Apple (Grand Central Dispatch), Windows thread pools, and Emscripten/WebAssembly builds per STLAB_TASK_SYSTEM.

Submit work through high_executor, default_executor, or low_executor as priority hints; the runtime prefers high, then default, then low, but order is not strict under load. Threadless Emscripten routes all three priorities asynchronously to the main runtime queue. Tasks must return control to the host event loop for other tasks to make progress. During cooperative pre_exit(), these tasks and their descendants drain ahead of deferred main tasks. Submission closes after the last executor target and its captures are destroyed. A subsequent ordinary main task is the shutdown-completion fence.

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. On threaded task systems, neither may call pre_exit() because core retirement waits for their completion; violations assert and terminate.

Note

Call pre_exit() before normal process exit when using these executors so detached tasks do not overlap teardown of globals or other exit handlers (the implementation registers a pre-exit hook). std::quick_exit() is an alternative when it fits your program. In cooperative builds, do not exit immediately on return from pre_exit(); enqueue final exit through main_executor so it follows asynchronous retirement and producer main work.