# Understanding the ASIO Executor Model and Execution Context > Decouple async work submission from execution with ASIO executors and contexts. Learn safe, composable scheduling across threads and I/O services for better C++ asynchronous programming. - Repository: [chriskohlhoff/asio](https://github.com/chriskohlhoff/asio) - Tags: deep-dive - Published: 2026-07-11 --- **The ASIO executor model decouples asynchronous work submission from execution by using type-erased executor wrappers that forward callable objects to concrete execution contexts, enabling safe, composable scheduling across threads and I/O services.** The `chriskohlhoff/asio` library provides a sophisticated concurrency framework built on two foundational abstractions: **executors** and **execution contexts**. Understanding how the ASIO executor model interacts with execution contexts is essential for writing high-performance networking code and custom asynchronous operations. This analysis examines the source code in [`asio/execution_context.hpp`](https://github.com/chriskohlhoff/asio/blob/main/asio/execution_context.hpp), [`asio/executor.hpp`](https://github.com/chriskohlhoff/asio/blob/main/asio/executor.hpp), and [`asio/execution.hpp`](https://github.com/chriskohlhoff/asio/blob/main/asio/execution.hpp) to explain the architectural relationship between these components. ## Core Architectural Components ### The Execution Context Base Class At the root of the hierarchy lies the abstract `execution_context` class defined in [`asio/execution_context.hpp`](https://github.com/chriskohlhoff/asio/blob/main/asio/execution_context.hpp). This class provides the lifecycle methods `shutdown()` and `destroy()`, which concrete contexts like `io_context` implement to manage resource cleanup and service termination. The base class also maintains a polymorphic service registry and exposes `notify_fork()` for handling `fork_prepare`, `fork_parent`, and `fork_child` events during process forking. Concrete execution contexts expose their associated executor via the `get_executor()` method, allowing handlers to obtain a scheduler without knowing the specific context type. ### The Polymorphic Executor Wrapper The `executor` class in [`asio/executor.hpp`](https://github.com/chriskohlhoff/asio/blob/main/asio/executor.hpp) acts as a type-erased wrapper around any executor satisfying ASIO's requirements. It stores an implementation pointer (`impl_`) and forwards scheduling calls—`dispatch()`, `post()`, and `defer()`—to the concrete executor held by the context. This design makes executors **copyable** and **move-aware**, allowing them to be stored in standard containers and passed by value while maintaining reference semantics to the underlying context. The class provides template constructors that implicitly wrap user-provided executors, enabling seamless integration with custom scheduling policies like strands or thread pools. ## Work Tracking and Context Lifecycle Executors prevent premature context shutdown through explicit work tracking. When a handler is submitted via `on_work_started()`, the execution context increments an internal counter that prevents the `run()` loop from returning. After the handler completes, `on_work_finished()` decrements this counter, allowing the context to stop only when all pending work has been processed. This mechanism ensures that asynchronous operations complete even if the original posting object goes out of scope, as the executor maintains the context's viability for the duration of the work unit. ## Scheduling Operations Through Executors The free functions declared in [`asio/execution.hpp`](https://github.com/chriskohlhoff/asio/blob/main/asio/execution.hpp)—`asio::post()`, `asio::dispatch()`, and `asio::defer()`—provide the primary interface for submitting work to executors. These functions accept any executor-like object and forward the callable to the appropriate scheduling method. **Dispatch** executes the handler immediately if the context is running on the current thread; **post** always queues the handler for later execution; **defer** behaves like post but allows the executor to optimize for tail-call elimination. This triad gives developers fine-grained control over execution timing while remaining agnostic to the specific context implementation. ## Practical Implementation Examples ```cpp #include #include // ------------------------------------------------------------ // 1. Using the default executor of an io_context. asio::io_context ctx; // The executor associated with the io_context. asio::executor ex = ctx.get_executor(); // Post a simple lambda; it will be executed by ctx.run(). asio::post(ex, [] { std::cout << "Hello from the default executor\n"; }); ctx.run(); // <-- processes the posted work // ------------------------------------------------------------ ``` ```cpp // ------------------------------------------------------------ // 2. Creating a custom executor (a strand) that guarantees // serialized execution of handlers. asio::io_context ctx2; asio::strand strand(ctx2.get_executor()); // Two tasks posted through the strand will never run concurrently. asio::post(strand, [] { std::cout << "Task A\n"; }); asio::post(strand, [] { std::cout << "Task B\n"; }); ctx2.run(); // ------------------------------------------------------------ ``` ```cpp // ------------------------------------------------------------ // 3. Explicitly using the execution_context API. asio::execution_context& ec = ctx; // up‑cast to the base class ec.on_work_started(); // inform the context of pending work // … schedule work … ec.on_work_finished(); // tell the context work is done // ------------------------------------------------------------ ``` ## Key Source Files - **[`include/asio/execution_context.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/execution_context.hpp)**: Defines the abstract `execution_context` class, service registration, and fork-event handling hooks according to the `chriskohlhoff/asio` source. - **[`include/asio/executor.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/executor.hpp)**: Implements the polymorphic `executor` wrapper with type-erased storage (`impl_`) and forwarding logic for `dispatch()`, `post()`, and `defer()`. - **[`include/asio/execution.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/execution.hpp)**: Declares the free functions `asio::post()`, `asio::dispatch()`, and `asio::defer()` that accept generic executors and forward to the executor’s methods. - **[`include/asio/io_context.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/io_context.hpp)**: Concrete execution context implementation that provides `io_context::executor_type` and the core I/O run-loop mechanics. ## Summary - **Decoupling**: The ASIO executor model separates handler submission (`executor`) from handler execution (`execution_context`), allowing code to remain agnostic to the underlying concurrency mechanism. - **Type Erasure**: The `executor` class uses an internal `impl_` pointer to wrap any executor type, enabling polymorphic scheduling without template pollution in user code. - **Lifecycle Safety**: `on_work_started()` and `on_work_finished()` ensure execution contexts remain alive while pending asynchronous operations exist, preventing race conditions during shutdown. - **Flexible Scheduling**: The `dispatch()`, `post()`, and `defer()` methods provide distinct semantics for immediate, queued, and deferred execution, accessible through both member functions and free functions in [`asio/execution.hpp`](https://github.com/chriskohlhoff/asio/blob/main/asio/execution.hpp). ## Frequently Asked Questions ### What is the difference between an executor and an execution context in ASIO? An **execution context** (such as `io_context`) represents the physical environment where function objects run, managing threads, services, and the event loop. An **executor** is a lightweight, copyable handle that knows *how* to submit work to that context. While the context provides the actual execution resources, the executor provides the interface for safely enqueueing handlers from any thread. ### How does ASIO prevent an execution context from stopping while work is pending? ASIO uses explicit work tracking through the `on_work_started()` and `on_work_finished()` methods defined in `execution_context`. When a handler is submitted, the executor calls `on_work_started()`, incrementing a counter that prevents the context's `run()` function from returning. Once the handler completes, `on_work_finished()` decrements the counter, allowing shutdown only when the count reaches zero. ### When should I use dispatch() versus post() on an ASIO executor? Use **`dispatch()`** when the handler should execute immediately if the calling thread is already inside the context's `run()` loop, avoiding unnecessary queuing overhead. Use **`post()`** when the handler must be queued for later execution regardless of the current thread, ensuring serialization and preventing stack overflow in recursive scenarios. ### Can I create custom executors that work with ASIO's io_context? Yes. Any class satisfying the executor requirements—providing `context()`, `on_work_started()`, `on_work_finished()`, `dispatch()`, `post()`, and `defer()` members—can be wrapped by `asio::executor` or used directly with ASIO's algorithm hooks. The `strand<>` template demonstrates this pattern by wrapping an underlying executor while adding serialization guarantees.