Diff coverage report for

//

//

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2026 Steve Gerbino

// Copyright (c) 2026 Steve Gerbino

// Copyright (c) 2026 Michael Vandeberg

// Copyright (c) 2026 Michael Vandeberg

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/cppalliance/corosio

// Official repository: https://github.com/cppalliance/corosio

//

//

#ifndef BOOST_COROSIO_IO_CONTEXT_HPP

#ifndef BOOST_COROSIO_IO_CONTEXT_HPP

#define BOOST_COROSIO_IO_CONTEXT_HPP

#define BOOST_COROSIO_IO_CONTEXT_HPP

#include <boost/corosio/detail/config.hpp>

#include <boost/corosio/detail/config.hpp>

#include <boost/corosio/detail/continuation_op.hpp>

#include <boost/corosio/detail/continuation_op.hpp>

#include <boost/corosio/detail/platform.hpp>

#include <boost/corosio/detail/platform.hpp>

#include <boost/corosio/detail/scheduler.hpp>

#include <boost/corosio/detail/scheduler.hpp>

#include <boost/capy/continuation.hpp>

#include <boost/capy/continuation.hpp>

#include <boost/capy/ex/execution_context.hpp>

#include <boost/capy/ex/execution_context.hpp>

#include <chrono>

#include <chrono>

#include <coroutine>

#include <coroutine>

#include <cstddef>

#include <cstddef>

#include <limits>

#include <limits>

#include <thread>

#include <thread>

namespace boost::corosio {

namespace boost::corosio {

/** Runtime tuning options for @ref io_context.

/** Runtime tuning options for @ref io_context.

    All fields have defaults that match the library's built-in

    All fields have defaults that match the library's built-in

    values, so constructing a default `io_context_options` produces

    values, so constructing a default `io_context_options` produces

    identical behavior to an unconfigured context.

    identical behavior to an unconfigured context.

    Options that apply only to a specific backend family are

    Options that apply only to a specific backend family are

    silently ignored when the active backend does not support them.

    silently ignored when the active backend does not support them.

    @par Example

    @par Example

    @code

    @code

    io_context_options opts;

    io_context_options opts;

    opts.max_events_per_poll  = 256;   // larger batch per syscall

    opts.max_events_per_poll  = 256;   // larger batch per syscall

    opts.inline_budget_max    = 32;    // more speculative completions

    opts.inline_budget_max    = 32;    // more speculative completions

    opts.thread_pool_size     = 4;     // more file-I/O workers

    opts.thread_pool_size     = 4;     // more file-I/O workers

    io_context ioc(opts);

    io_context ioc(opts);

    @endcode

    @endcode

    @see io_context, native_io_context

    @see io_context, native_io_context

*/

*/

struct io_context_options

struct io_context_options

{

{

    /** Maximum events fetched per reactor poll call.

    /** Maximum events fetched per reactor poll call.

        Controls the buffer size passed to `epoll_wait()` or

        Controls the buffer size passed to `epoll_wait()` or

        `kevent()`. Larger values reduce syscall frequency under

        `kevent()`. Larger values reduce syscall frequency under

        high load; smaller values improve fairness between

        high load; smaller values improve fairness between

        connections. Ignored on IOCP and select backends.

        connections. Ignored on IOCP and select backends.

    */

    */

    unsigned max_events_per_poll = 128;

    unsigned max_events_per_poll = 128;

    /** Starting inline completion budget per handler chain.

    /** Starting inline completion budget per handler chain.

        After a posted handler executes, the reactor grants this

        After a posted handler executes, the reactor grants this

        many speculative inline completions before forcing a

        many speculative inline completions before forcing a

        re-queue. Applies to reactor backends only.

        re-queue. Applies to reactor backends only.

    */

    */

    unsigned inline_budget_initial = 2;

    unsigned inline_budget_initial = 2;

    /** Hard ceiling on adaptive inline budget ramp-up.

    /** Hard ceiling on adaptive inline budget ramp-up.

        The budget doubles each cycle it is fully consumed, up to

        The budget doubles each cycle it is fully consumed, up to

        this limit. Applies to reactor backends only.

        this limit. Applies to reactor backends only.

    */

    */

    unsigned inline_budget_max = 16;

    unsigned inline_budget_max = 16;

    /** Inline budget when no other thread assists the reactor.

    /** Inline budget when no other thread assists the reactor.

        When only one thread is running the event loop, this

        When only one thread is running the event loop, this

        value caps the inline budget to preserve fairness.

        value caps the inline budget to preserve fairness.

        Applies to reactor backends only.

        Applies to reactor backends only.

    */

    */

    unsigned unassisted_budget = 4;

    unsigned unassisted_budget = 4;

    /** Maximum `GetQueuedCompletionStatus` timeout in milliseconds.

    /** Maximum `GetQueuedCompletionStatus` timeout in milliseconds.

        Bounds how long the IOCP scheduler blocks between timer

        Bounds how long the IOCP scheduler blocks between timer

        rechecks. Lower values improve timer responsiveness at the

        rechecks. Lower values improve timer responsiveness at the

        cost of more syscalls. Applies to IOCP only.

        cost of more syscalls. Applies to IOCP only.

    */

    */

    unsigned gqcs_timeout_ms = 500;

    unsigned gqcs_timeout_ms = 500;

    /** Thread pool size for blocking I/O (file I/O, DNS resolution).

    /** Thread pool size for blocking I/O (file I/O, DNS resolution).

        Sets the number of worker threads in the shared thread pool

        Sets the number of worker threads in the shared thread pool

        used by POSIX file services and DNS resolution. Must be at

        used by POSIX file services and DNS resolution. Must be at

        least 1. Applies to POSIX backends only; ignored on IOCP

        least 1. Applies to POSIX backends only; ignored on IOCP

        where file I/O uses native overlapped I/O.

        where file I/O uses native overlapped I/O.

    */

    */

    unsigned thread_pool_size = 1;

    unsigned thread_pool_size = 1;

    /** Enable single-threaded mode (disable scheduler locking).

    /** Enable single-threaded mode (disable scheduler locking).

        When true, the scheduler skips all mutex lock/unlock and

        When true, the scheduler skips all mutex lock/unlock and

        condition variable operations on the hot path. This

        condition variable operations on the hot path. This

        eliminates synchronization overhead when only one thread

        eliminates synchronization overhead when only one thread

        calls `run()`.

        calls `run()`.

        @par Restrictions

        @par Restrictions

        - Only one thread may call `run()` (or any run variant).

        - Only one thread may call `run()` (or any run variant).

        - Posting work from another thread is undefined behavior.

        - Posting work from another thread is undefined behavior.

        - DNS resolution returns `operation_not_supported`.

        - DNS resolution returns `operation_not_supported`.

        - POSIX file I/O returns `operation_not_supported`.

        - POSIX file I/O returns `operation_not_supported`.

        - Signal sets should not be shared across contexts.

        - Signal sets should not be shared across contexts.

    */

    */

    bool single_threaded = false;

    bool single_threaded = false;

};

};

namespace detail {

namespace detail {

class timer_service;

class timer_service;

struct timer_service_access;

struct timer_service_access;

} // namespace detail

} // namespace detail

/** An I/O context for running asynchronous operations.

/** An I/O context for running asynchronous operations.

    The io_context provides an execution environment for async

    The io_context provides an execution environment for async

    operations. It maintains a queue of pending work items and

    operations. It maintains a queue of pending work items and

    processes them when `run()` is called.

    processes them when `run()` is called.

    The default and unsigned constructors select the platform's

    The default and unsigned constructors select the platform's

    native backend:

    native backend:

    - Windows: IOCP

    - Windows: IOCP

    - Linux: epoll

    - Linux: epoll

    - BSD/macOS: kqueue

    - BSD/macOS: kqueue

    - Other POSIX: select

    - Other POSIX: select

    The template constructor accepts a backend tag value to

    The template constructor accepts a backend tag value to

    choose a specific backend at compile time:

    choose a specific backend at compile time:

    @par Example

    @par Example

    @code

    @code

    io_context ioc;                   // platform default

    io_context ioc;                   // platform default

    io_context ioc2(corosio::epoll);  // explicit backend

    io_context ioc2(corosio::epoll);  // explicit backend

    @endcode

    @endcode

    @par Thread Safety

    @par Thread Safety

    Distinct objects: Safe.@n

    Distinct objects: Safe.@n

    Shared objects: Safe, if using a concurrency hint greater

    Shared objects: Safe, if using a concurrency hint greater

    than 1.

    than 1.

    @see epoll_t, select_t, kqueue_t, iocp_t

    @see epoll_t, select_t, kqueue_t, iocp_t

*/

*/

class BOOST_COROSIO_DECL io_context : public capy::execution_context

class BOOST_COROSIO_DECL io_context : public capy::execution_context

{

{

    friend struct detail::timer_service_access;

    friend struct detail::timer_service_access;

    /// Pre-create services that depend on options (before construct).

    /// Pre-create services that depend on options (before construct).

    void apply_options_pre_(io_context_options const& opts);

    void apply_options_pre_(io_context_options const& opts);

    /// Apply runtime tuning to the scheduler (after construct).

    /// Apply runtime tuning to the scheduler (after construct).

    void apply_options_post_(io_context_options const& opts);

    void apply_options_post_(io_context_options const& opts);

protected:

protected:

    detail::timer_service* timer_svc_ = nullptr;

    detail::timer_service* timer_svc_ = nullptr;

    detail::scheduler* sched_;

    detail::scheduler* sched_;

public:

public:

    /** The executor type for this context. */

    /** The executor type for this context. */

    class executor_type;

    class executor_type;

    /** Construct with default concurrency and platform backend. */

    /** Construct with default concurrency and platform backend. */

    io_context();

    io_context();

    /** Construct with a concurrency hint and platform backend.

    /** Construct with a concurrency hint and platform backend.

        @param concurrency_hint Hint for the number of threads

        @param concurrency_hint Hint for the number of threads

            that will call `run()`.

            that will call `run()`.

    */

    */

    explicit io_context(unsigned concurrency_hint);

    explicit io_context(unsigned concurrency_hint);

    /** Construct with runtime tuning options and platform backend.

    /** Construct with runtime tuning options and platform backend.

        @param opts Runtime options controlling scheduler and

        @param opts Runtime options controlling scheduler and

            service behavior.

            service behavior.

        @param concurrency_hint Hint for the number of threads

        @param concurrency_hint Hint for the number of threads

            that will call `run()`.

            that will call `run()`.

    */

    */

    explicit io_context(

    explicit io_context(

        io_context_options const& opts,

        io_context_options const& opts,

        unsigned concurrency_hint = std::thread::hardware_concurrency());

        unsigned concurrency_hint = std::thread::hardware_concurrency());

    /** Construct with an explicit backend tag.

    /** Construct with an explicit backend tag.

        @param backend The backend tag value selecting the I/O

        @param backend The backend tag value selecting the I/O

            multiplexer (e.g. `corosio::epoll`).

            multiplexer (e.g. `corosio::epoll`).

        @param concurrency_hint Hint for the number of threads

        @param concurrency_hint Hint for the number of threads

            that will call `run()`.

            that will call `run()`.

    */

    */

    template<class Backend>

    template<class Backend>

        requires requires { Backend::construct; }

        requires requires { Backend::construct; }

        Backend backend,

        Backend backend,

        unsigned concurrency_hint = std::thread::hardware_concurrency())

        unsigned concurrency_hint = std::thread::hardware_concurrency())

        : capy::execution_context(this)

        : capy::execution_context(this)

    {

    {

        (void)backend;

        (void)backend;

    /** Construct with an explicit backend tag and runtime options.

    /** Construct with an explicit backend tag and runtime options.

        @param backend The backend tag value selecting the I/O

        @param backend The backend tag value selecting the I/O

            multiplexer (e.g. `corosio::epoll`).

            multiplexer (e.g. `corosio::epoll`).

        @param opts Runtime options controlling scheduler and

        @param opts Runtime options controlling scheduler and

            service behavior.

            service behavior.

        @param concurrency_hint Hint for the number of threads

        @param concurrency_hint Hint for the number of threads

            that will call `run()`.

            that will call `run()`.

    */

    */

    template<class Backend>

    template<class Backend>

        requires requires { Backend::construct; }

        requires requires { Backend::construct; }

    explicit io_context(

    explicit io_context(

        Backend backend,

        Backend backend,

        io_context_options const& opts,

        io_context_options const& opts,

        unsigned concurrency_hint = std::thread::hardware_concurrency())

        unsigned concurrency_hint = std::thread::hardware_concurrency())

        : capy::execution_context(this)

        : capy::execution_context(this)

        , sched_(nullptr)

        , sched_(nullptr)

    {

    {

        (void)backend;

        (void)backend;

        apply_options_pre_(opts);

        apply_options_pre_(opts);

        sched_ = &Backend::construct(*this, concurrency_hint);

        sched_ = &Backend::construct(*this, concurrency_hint);

        apply_options_post_(opts);

        apply_options_post_(opts);

    }

    }

    ~io_context();

    ~io_context();

    io_context(io_context const&)            = delete;

    io_context(io_context const&)            = delete;

    io_context& operator=(io_context const&) = delete;

    io_context& operator=(io_context const&) = delete;

    /** Return an executor for this context.

    /** Return an executor for this context.

        The returned executor can be used to dispatch coroutines

        The returned executor can be used to dispatch coroutines

        and post work items to this context.

        and post work items to this context.

        @return An executor associated with this context.

        @return An executor associated with this context.

    */

    */

    executor_type get_executor() const noexcept;

    executor_type get_executor() const noexcept;

    /** Signal the context to stop processing.

    /** Signal the context to stop processing.

        This causes `run()` to return as soon as possible. Any pending

        This causes `run()` to return as soon as possible. Any pending

        work items remain queued.

        work items remain queued.

    */

    */

    {

    {

    /** Return whether the context has been stopped.

    /** Return whether the context has been stopped.

        @return `true` if `stop()` has been called and `restart()`

        @return `true` if `stop()` has been called and `restart()`

            has not been called since.

            has not been called since.

    */

    */

    {

    {

    }

    }

    /** Restart the context after being stopped.

    /** Restart the context after being stopped.

        This function must be called before `run()` can be called

        This function must be called before `run()` can be called

        again after `stop()` has been called.

        again after `stop()` has been called.

    */

    */

    {

    {

    /** Process all pending work items.

    /** Process all pending work items.

        This function blocks until all pending work items have been

        This function blocks until all pending work items have been

        executed or `stop()` is called. The context is stopped

        executed or `stop()` is called. The context is stopped

        when there is no more outstanding work.

        when there is no more outstanding work.

        @note The context must be restarted with `restart()` before

        @note The context must be restarted with `restart()` before

            calling this function again after it returns.

            calling this function again after it returns.

        @return The number of handlers executed.

        @return The number of handlers executed.

    */

    */

    {

    {

    }

    }

    /** Process at most one pending work item.

    /** Process at most one pending work item.

        This function blocks until one work item has been executed

        This function blocks until one work item has been executed

        or `stop()` is called. The context is stopped when there

        or `stop()` is called. The context is stopped when there

        is no more outstanding work.

        is no more outstanding work.

        @note The context must be restarted with `restart()` before

        @note The context must be restarted with `restart()` before

            calling this function again after it returns.

            calling this function again after it returns.

        @return The number of handlers executed (0 or 1).

        @return The number of handlers executed (0 or 1).

    */

    */

    {

    {

    }

    }

    /** Process work items for the specified duration.

    /** Process work items for the specified duration.

        This function blocks until work items have been executed for

        This function blocks until work items have been executed for

        the specified duration, or `stop()` is called. The context

        the specified duration, or `stop()` is called. The context

        is stopped when there is no more outstanding work.

        is stopped when there is no more outstanding work.

        @note The context must be restarted with `restart()` before

        @note The context must be restarted with `restart()` before

            calling this function again after it returns.

            calling this function again after it returns.

        @param rel_time The duration for which to process work.

        @param rel_time The duration for which to process work.

        @return The number of handlers executed.

        @return The number of handlers executed.

    */

    */

    template<class Rep, class Period>

    template<class Rep, class Period>

    {

    {

    }

    }

    /** Process work items until the specified time.

    /** Process work items until the specified time.

        This function blocks until the specified time is reached

        This function blocks until the specified time is reached

        or `stop()` is called. The context is stopped when there

        or `stop()` is called. The context is stopped when there

        is no more outstanding work.

        is no more outstanding work.

        @note The context must be restarted with `restart()` before

        @note The context must be restarted with `restart()` before

            calling this function again after it returns.

            calling this function again after it returns.

        @param abs_time The time point until which to process work.

        @param abs_time The time point until which to process work.

        @return The number of handlers executed.

        @return The number of handlers executed.

    */

    */

    template<class Clock, class Duration>

    template<class Clock, class Duration>

    std::size_t

    std::size_t

    {

    {

    }

    }

    /** Process at most one work item for the specified duration.

    /** Process at most one work item for the specified duration.

        This function blocks until one work item has been executed,

        This function blocks until one work item has been executed,

        the specified duration has elapsed, or `stop()` is called.

        the specified duration has elapsed, or `stop()` is called.

        The context is stopped when there is no more outstanding work.

        The context is stopped when there is no more outstanding work.

        @note The context must be restarted with `restart()` before

        @note The context must be restarted with `restart()` before

            calling this function again after it returns.

            calling this function again after it returns.

        @param rel_time The duration for which the call may block.

        @param rel_time The duration for which the call may block.

        @return The number of handlers executed (0 or 1).

        @return The number of handlers executed (0 or 1).

    */

    */

    template<class Rep, class Period>

    template<class Rep, class Period>

    {

    {

    }

    }

    /** Process at most one work item until the specified time.

    /** Process at most one work item until the specified time.

        This function blocks until one work item has been executed,

        This function blocks until one work item has been executed,

        the specified time is reached, or `stop()` is called.

        the specified time is reached, or `stop()` is called.

        The context is stopped when there is no more outstanding work.

        The context is stopped when there is no more outstanding work.

        @note The context must be restarted with `restart()` before

        @note The context must be restarted with `restart()` before

            calling this function again after it returns.

            calling this function again after it returns.

        @param abs_time The time point until which the call may block.

        @param abs_time The time point until which the call may block.

        @return The number of handlers executed (0 or 1).

        @return The number of handlers executed (0 or 1).

    */

    */

    template<class Clock, class Duration>

    template<class Clock, class Duration>

    std::size_t

    std::size_t

    {

    {

        {

        {

                static_cast<long>(

                static_cast<long>(

                        rel_time)

                        rel_time)

        }

        }

    }

    }

    /** Process all ready work items without blocking.

    /** Process all ready work items without blocking.

        This function executes all work items that are ready to run

        This function executes all work items that are ready to run

        without blocking for more work. The context is stopped

        without blocking for more work. The context is stopped

        when there is no more outstanding work.

        when there is no more outstanding work.

        @note The context must be restarted with `restart()` before

        @note The context must be restarted with `restart()` before

            calling this function again after it returns.

            calling this function again after it returns.

        @return The number of handlers executed.

        @return The number of handlers executed.

    */

    */

    {

    {

    }

    }

    /** Process at most one ready work item without blocking.

    /** Process at most one ready work item without blocking.

        This function executes at most one work item that is ready

        This function executes at most one work item that is ready

        to run without blocking for more work. The context is

        to run without blocking for more work. The context is

        stopped when there is no more outstanding work.

        stopped when there is no more outstanding work.

        @note The context must be restarted with `restart()` before

        @note The context must be restarted with `restart()` before

            calling this function again after it returns.

            calling this function again after it returns.

        @return The number of handlers executed (0 or 1).

        @return The number of handlers executed (0 or 1).

    */

    */

    {

    {

    }

    }

};

};

/** An executor for dispatching work to an I/O context.

/** An executor for dispatching work to an I/O context.

    The executor provides the interface for posting work items and

    The executor provides the interface for posting work items and

    dispatching coroutines to the associated context. It satisfies

    dispatching coroutines to the associated context. It satisfies

    the `capy::Executor` concept.

    the `capy::Executor` concept.

    Executors are lightweight handles that can be copied and compared

    Executors are lightweight handles that can be copied and compared

    for equality. Two executors compare equal if they refer to the

    for equality. Two executors compare equal if they refer to the

    same context.

    same context.

    @par Thread Safety

    @par Thread Safety

    Distinct objects: Safe.@n

    Distinct objects: Safe.@n

    Shared objects: Safe.

    Shared objects: Safe.

*/

*/

class io_context::executor_type

class io_context::executor_type

{

{

    io_context* ctx_ = nullptr;

    io_context* ctx_ = nullptr;

public:

public:

    /** Default constructor.

    /** Default constructor.

        Constructs an executor not associated with any context.

        Constructs an executor not associated with any context.

    */

    */

    executor_type() = default;

    executor_type() = default;

    /** Construct an executor from a context.

    /** Construct an executor from a context.

        @param ctx The context to associate with this executor.

        @param ctx The context to associate with this executor.

    */

    */

    /** Return a reference to the associated execution context.

    /** Return a reference to the associated execution context.

        @return Reference to the context.

        @return Reference to the context.

    */

    */

    {

    {

    }

    }

    /** Check if the current thread is running this executor's context.

    /** Check if the current thread is running this executor's context.

        @return `true` if `run()` is being called on this thread.

        @return `true` if `run()` is being called on this thread.

    */

    */

    {

    {

    }

    }

    /** Informs the executor that work is beginning.

    /** Informs the executor that work is beginning.

        Must be paired with `on_work_finished()`.

        Must be paired with `on_work_finished()`.

    */

    */

    {

    {

    /** Informs the executor that work has completed.

    /** Informs the executor that work has completed.

        @par Preconditions

        @par Preconditions

        A preceding call to `on_work_started()` on an equal executor.

        A preceding call to `on_work_started()` on an equal executor.

    */

    */

    {

    {

    /** Dispatch a continuation.

    /** Dispatch a continuation.

        Returns a handle for symmetric transfer. If called from

        Returns a handle for symmetric transfer. If called from

        within `run()`, returns `c.h`. Otherwise posts the

        within `run()`, returns `c.h`. Otherwise posts the

        enclosing continuation_op as a scheduler_op for later

        enclosing continuation_op as a scheduler_op for later

        execution and returns `std::noop_coroutine()`.

        execution and returns `std::noop_coroutine()`.

        @param c The continuation to dispatch. Must be the `cont`

        @param c The continuation to dispatch. Must be the `cont`

                 member of a `detail::continuation_op`.

                 member of a `detail::continuation_op`.

        @return A handle for symmetric transfer or `std::noop_coroutine()`.

        @return A handle for symmetric transfer or `std::noop_coroutine()`.

    */

    */

    {

    {

    }

    }

    /** Post a continuation for deferred execution.

    /** Post a continuation for deferred execution.