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/platform.hpp>

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

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

#include <boost/corosio/detail/scheduler.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 {

namespace detail {

namespace detail {

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;

protected:

protected:

    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 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;

    ~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 coroutine handle.

    /** Dispatch a coroutine handle.

        Returns a handle for symmetric transfer. If called from

        Returns a handle for symmetric transfer. If called from

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

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

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

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

        @param h The coroutine handle to dispatch.

        @param h The coroutine handle to dispatch.

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

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

    */

    */

    {

    {

    }

    }

    /** Post a coroutine for deferred execution.

    /** Post a coroutine for deferred execution.

        The coroutine will be resumed during a subsequent call to

        The coroutine will be resumed during a subsequent call to

        `run()`.

        `run()`.

        @param h The coroutine handle to post.

        @param h The coroutine handle to post.

    */

    */

    {

    {

    /** Compare two executors for equality.

    /** Compare two executors for equality.

        @return `true` if both executors refer to the same context.

        @return `true` if both executors refer to the same context.

    */

    */

    {

    {

    }

    }

    /** Compare two executors for inequality.

    /** Compare two executors for inequality.

        @return `true` if the executors refer to different contexts.

        @return `true` if the executors refer to different contexts.

    */

    */

    bool operator!=(executor_type const& other) const noexcept

    bool operator!=(executor_type const& other) const noexcept

    {

    {

        return ctx_ != other.ctx_;

        return ctx_ != other.ctx_;

    }

    }

};

};

inline io_context::executor_type

inline io_context::executor_type

{

{

}

}

} // namespace boost::corosio

} // namespace boost::corosio

#endif // BOOST_COROSIO_IO_CONTEXT_HPP

#endif // BOOST_COROSIO_IO_CONTEXT_HPP