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

//

//

// 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_TCP_ACCEPTOR_HPP

#ifndef BOOST_COROSIO_TCP_ACCEPTOR_HPP

#define BOOST_COROSIO_TCP_ACCEPTOR_HPP

#define BOOST_COROSIO_TCP_ACCEPTOR_HPP

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

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

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

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

#include <boost/corosio/io/io_object.hpp>

#include <boost/corosio/io/io_object.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/corosio/endpoint.hpp>

#include <boost/corosio/endpoint.hpp>

#include <boost/corosio/tcp.hpp>

#include <boost/corosio/tcp.hpp>

#include <boost/corosio/tcp_socket.hpp>

#include <boost/corosio/tcp_socket.hpp>

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

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

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

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

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

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

#include <boost/capy/concept/executor.hpp>

#include <boost/capy/concept/executor.hpp>

#include <system_error>

#include <system_error>

#include <concepts>

#include <concepts>

#include <coroutine>

#include <coroutine>

#include <memory>

#include <cstddef>

#include <cstddef>

#include <stop_token>

#include <stop_token>

#include <type_traits>

#include <type_traits>

namespace boost::corosio {

namespace boost::corosio {

/** An asynchronous TCP acceptor for coroutine I/O.

/** An asynchronous TCP acceptor for coroutine I/O.

    This class provides asynchronous TCP accept operations that return

    This class provides asynchronous TCP accept operations that return

    awaitable types. The acceptor binds to a local endpoint and listens

    awaitable types. The acceptor binds to a local endpoint and listens

    for incoming connections.

    for incoming connections.

    Each accept operation participates in the affine awaitable protocol,

    Each accept operation participates in the affine awaitable protocol,

    ensuring coroutines resume on the correct executor.

    ensuring coroutines resume on the correct executor.

    @par Thread Safety

    @par Thread Safety

    Distinct objects: Safe.@n

    Distinct objects: Safe.@n

    Shared objects: Unsafe. An acceptor must not have concurrent accept

    Shared objects: Unsafe. An acceptor must not have concurrent accept

    operations.

    operations.

    @par Semantics

    @par Semantics

    Wraps the platform TCP listener. Operations dispatch to

    Wraps the platform TCP listener. Operations dispatch to

    OS accept APIs via the io_context reactor.

    OS accept APIs via the io_context reactor.

    @par Example

    @par Example

    @code

    @code

    // Convenience constructor: open + SO_REUSEADDR + bind + listen

    // Convenience constructor: open + SO_REUSEADDR + bind + listen

    io_context ioc;

    io_context ioc;

    tcp_acceptor acc( ioc, endpoint( 8080 ) );

    tcp_acceptor acc( ioc, endpoint( 8080 ) );

    tcp_socket peer( ioc );

    tcp_socket peer( ioc );

    auto [ec] = co_await acc.accept( peer );

    auto [ec] = co_await acc.accept( peer );

    if ( !ec ) {

    if ( !ec ) {

        // peer is now a connected socket

        // peer is now a connected socket

        auto [ec2, n] = co_await peer.read_some( buf );

        auto [ec2, n] = co_await peer.read_some( buf );

    }

    }

    @endcode

    @endcode

    @par Example

    @par Example

    @code

    @code

    // Fine-grained setup

    // Fine-grained setup

    tcp_acceptor acc( ioc );

    tcp_acceptor acc( ioc );

    acc.open( tcp::v6() );

    acc.open( tcp::v6() );

    acc.set_option( socket_option::reuse_address( true ) );

    acc.set_option( socket_option::reuse_address( true ) );

    acc.set_option( socket_option::v6_only( true ) );

    acc.set_option( socket_option::v6_only( true ) );

    if ( auto ec = acc.bind( endpoint( ipv6_address::any(), 8080 ) ) )

    if ( auto ec = acc.bind( endpoint( ipv6_address::any(), 8080 ) ) )

        return ec;

        return ec;

    if ( auto ec = acc.listen() )

    if ( auto ec = acc.listen() )

        return ec;

        return ec;

    @endcode

    @endcode

*/

*/

class BOOST_COROSIO_DECL tcp_acceptor : public io_object

class BOOST_COROSIO_DECL tcp_acceptor : public io_object

{

{

    struct accept_awaitable

    struct accept_awaitable

    {

    {

        tcp_acceptor& acc_;

        tcp_acceptor& acc_;

        tcp_socket& peer_;

        tcp_socket& peer_;

        std::stop_token token_;

        std::stop_token token_;

        mutable std::error_code ec_;

        mutable std::error_code ec_;

        mutable io_object::implementation* peer_impl_ = nullptr;

        mutable io_object::implementation* peer_impl_ = nullptr;

        {

        {

        {

        {

        }

        }

        {

        {

        }

        }

            -> std::coroutine_handle<>

            -> std::coroutine_handle<>

        {

        {

        }

        }

    };

    };

public:

public:

    /** Destructor.

    /** Destructor.

        Closes the acceptor if open, cancelling any pending operations.

        Closes the acceptor if open, cancelling any pending operations.

    */

    */

    ~tcp_acceptor() override;

    ~tcp_acceptor() override;

    /** Construct an acceptor from an execution context.

    /** Construct an acceptor from an execution context.

        @param ctx The execution context that will own this acceptor.

        @param ctx The execution context that will own this acceptor.

    */

    */

    explicit tcp_acceptor(capy::execution_context& ctx);

    explicit tcp_acceptor(capy::execution_context& ctx);

    /** Convenience constructor: open + SO_REUSEADDR + bind + listen.

    /** Convenience constructor: open + SO_REUSEADDR + bind + listen.

        Creates a fully-bound listening acceptor in a single

        Creates a fully-bound listening acceptor in a single

        expression. The address family is deduced from @p ep.

        expression. The address family is deduced from @p ep.

        @param ctx The execution context that will own this acceptor.

        @param ctx The execution context that will own this acceptor.

        @param ep The local endpoint to bind to.

        @param ep The local endpoint to bind to.

        @param backlog The maximum pending connection queue length.

        @param backlog The maximum pending connection queue length.

        @throws std::system_error on bind or listen failure.

        @throws std::system_error on bind or listen failure.

    */

    */

    tcp_acceptor(

    tcp_acceptor(capy::execution_context& ctx, endpoint ep, int backlog = 128);

        capy::execution_context& ctx, endpoint ep, int backlog = 128 );

    /** Construct an acceptor from an executor.

    /** Construct an acceptor from an executor.

        The acceptor is associated with the executor's context.

        The acceptor is associated with the executor's context.

        @param ex The executor whose context will own the acceptor.

        @param ex The executor whose context will own the acceptor.

    */

    */

    template<class Ex>

    template<class Ex>

        requires(!std::same_as<std::remove_cvref_t<Ex>, tcp_acceptor>) &&

        requires(!std::same_as<std::remove_cvref_t<Ex>, tcp_acceptor>) &&

        capy::Executor<Ex>

        capy::Executor<Ex>

    explicit tcp_acceptor(Ex const& ex) : tcp_acceptor(ex.context())

    explicit tcp_acceptor(Ex const& ex) : tcp_acceptor(ex.context())

    {

    {

    }

    }

    /** Convenience constructor from an executor.

    /** Convenience constructor from an executor.

        @param ex The executor whose context will own the acceptor.

        @param ex The executor whose context will own the acceptor.

        @param ep The local endpoint to bind to.

        @param ep The local endpoint to bind to.

        @param backlog The maximum pending connection queue length.

        @param backlog The maximum pending connection queue length.

        @throws std::system_error on bind or listen failure.

        @throws std::system_error on bind or listen failure.

    */

    */

    template<class Ex>

    template<class Ex>

        requires capy::Executor<Ex>

        requires capy::Executor<Ex>

    tcp_acceptor(Ex const& ex, endpoint ep, int backlog = 128 )

    tcp_acceptor(Ex const& ex, endpoint ep, int backlog = 128)

        : tcp_acceptor(ex.context(), ep, backlog)

        : tcp_acceptor(ex.context(), ep, backlog)

    {

    {

    }

    }

    /** Move constructor.

    /** Move constructor.

        Transfers ownership of the acceptor resources.

        Transfers ownership of the acceptor resources.

        @param other The acceptor to move from.

        @param other The acceptor to move from.

        @pre No awaitables returned by @p other's methods exist.

        @pre No awaitables returned by @p other's methods exist.

        @pre The execution context associated with @p other must

        @pre The execution context associated with @p other must

            outlive this acceptor.

            outlive this acceptor.

    */

    */

    /** Move assignment operator.

    /** Move assignment operator.

        Closes any existing acceptor and transfers ownership.

        Closes any existing acceptor and transfers ownership.

        @param other The acceptor to move from.

        @param other The acceptor to move from.

        @pre No awaitables returned by either `*this` or @p other's

        @pre No awaitables returned by either `*this` or @p other's

            methods exist.

            methods exist.

        @pre The execution context associated with @p other must

        @pre The execution context associated with @p other must

            outlive this acceptor.

            outlive this acceptor.

        @return Reference to this acceptor.

        @return Reference to this acceptor.

    */

    */

    {

    {

        {

        {

        }

        }

    }

    }

    tcp_acceptor(tcp_acceptor const&)            = delete;

    tcp_acceptor(tcp_acceptor const&)            = delete;

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

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

    /** Create the acceptor socket without binding or listening.

    /** Create the acceptor socket without binding or listening.

        Creates a TCP socket with dual-stack enabled for IPv6.

        Creates a TCP socket with dual-stack enabled for IPv6.

        Does not set SO_REUSEADDR — call `set_option` explicitly

        Does not set SO_REUSEADDR — call `set_option` explicitly

        if needed.

        if needed.

        If the acceptor is already open, this function is a no-op.

        If the acceptor is already open, this function is a no-op.

        @param proto The protocol (IPv4 or IPv6). Defaults to

        @param proto The protocol (IPv4 or IPv6). Defaults to

            `tcp::v4()`.

            `tcp::v4()`.

        @throws std::system_error on failure.

        @throws std::system_error on failure.

        @par Example

        @par Example

        @code

        @code

        acc.open( tcp::v6() );

        acc.open( tcp::v6() );

        acc.set_option( socket_option::reuse_address( true ) );

        acc.set_option( socket_option::reuse_address( true ) );

        acc.bind( endpoint( ipv6_address::any(), 8080 ) );

        acc.bind( endpoint( ipv6_address::any(), 8080 ) );

        acc.listen();

        acc.listen();

        @endcode

        @endcode

        @see bind, listen

        @see bind, listen

    */

    */

    void open( tcp proto = tcp::v4() );

    void open(tcp proto = tcp::v4());

    /** Bind to a local endpoint.

    /** Bind to a local endpoint.

        The acceptor must be open. Binds the socket to @p ep and

        The acceptor must be open. Binds the socket to @p ep and

        caches the resolved local endpoint (useful when port 0 is

        caches the resolved local endpoint (useful when port 0 is

        used to request an ephemeral port).

        used to request an ephemeral port).

        @param ep The local endpoint to bind to.

        @param ep The local endpoint to bind to.

        @return An error code indicating success or the reason for

        @return An error code indicating success or the reason for

            failure.

            failure.

        @par Error Conditions

        @par Error Conditions

        @li `errc::address_in_use`: The endpoint is already in use.

        @li `errc::address_in_use`: The endpoint is already in use.

        @li `errc::address_not_available`: The address is not available

        @li `errc::address_not_available`: The address is not available

            on any local interface.

            on any local interface.

        @li `errc::permission_denied`: Insufficient privileges to bind

        @li `errc::permission_denied`: Insufficient privileges to bind

            to the endpoint (e.g., privileged port).

            to the endpoint (e.g., privileged port).

        @throws std::logic_error if the acceptor is not open.

        @throws std::logic_error if the acceptor is not open.

    */

    */

    [[nodiscard]] std::error_code bind( endpoint ep );

    [[nodiscard]] std::error_code bind(endpoint ep);

    /** Start listening for incoming connections.

    /** Start listening for incoming connections.

        The acceptor must be open and bound. Registers the acceptor

        The acceptor must be open and bound. Registers the acceptor

        with the platform reactor.

        with the platform reactor.

        @param backlog The maximum length of the queue of pending

        @param backlog The maximum length of the queue of pending

            connections. Defaults to 128.

            connections. Defaults to 128.

        @return An error code indicating success or the reason for

        @return An error code indicating success or the reason for

            failure.

            failure.

        @throws std::logic_error if the acceptor is not open.

        @throws std::logic_error if the acceptor is not open.

    */

    */

    [[nodiscard]] std::error_code listen( int backlog = 128 );

    [[nodiscard]] std::error_code listen(int backlog = 128);

    /** Close the acceptor.

    /** Close the acceptor.

        Releases acceptor resources. Any pending operations complete

        Releases acceptor resources. Any pending operations complete

        with `errc::operation_canceled`.

        with `errc::operation_canceled`.

    */

    */

    void close();

    void close();

    /** Check if the acceptor is listening.

    /** Check if the acceptor is listening.

        @return `true` if the acceptor is open and listening.

        @return `true` if the acceptor is open and listening.

    */

    */

    {

    {

    }

    }

    /** Initiate an asynchronous accept operation.

    /** Initiate an asynchronous accept operation.

        Accepts an incoming connection and initializes the provided

        Accepts an incoming connection and initializes the provided

        socket with the new connection. The acceptor must be listening

        socket with the new connection. The acceptor must be listening

        before calling this function.

        before calling this function.

        The operation supports cancellation via `std::stop_token` through

        The operation supports cancellation via `std::stop_token` through

        the affine awaitable protocol. If the associated stop token is

        the affine awaitable protocol. If the associated stop token is

        triggered, the operation completes immediately with

        triggered, the operation completes immediately with

        `errc::operation_canceled`.

        `errc::operation_canceled`.

        @param peer The socket to receive the accepted connection. Any

        @param peer The socket to receive the accepted connection. Any

            existing connection on this socket will be closed.

            existing connection on this socket will be closed.

        @return An awaitable that completes with `io_result<>`.

        @return An awaitable that completes with `io_result<>`.

            Returns success on successful accept, or an error code on

            Returns success on successful accept, or an error code on

            failure including:

            failure including:

            - operation_canceled: Cancelled via stop_token or cancel().

            - operation_canceled: Cancelled via stop_token or cancel().

                Check `ec == cond::canceled` for portable comparison.

                Check `ec == cond::canceled` for portable comparison.

        @par Preconditions

        @par Preconditions

        The acceptor must be listening (`is_open() == true`).

        The acceptor must be listening (`is_open() == true`).

        The peer socket must be associated with the same execution context.

        The peer socket must be associated with the same execution context.

        Both this acceptor and @p peer must outlive the returned

        Both this acceptor and @p peer must outlive the returned

        awaitable.

        awaitable.

        @par Example

        @par Example

        @code

        @code

        tcp_socket peer(ioc);

        tcp_socket peer(ioc);

        auto [ec] = co_await acc.accept(peer);

        auto [ec] = co_await acc.accept(peer);

        if (!ec) {

        if (!ec) {

            // Use peer socket

            // Use peer socket

        }

        }

        @endcode

        @endcode

    */

    */

    {

    {

    }

    }

    /** Cancel any pending asynchronous operations.

    /** Cancel any pending asynchronous operations.

        All outstanding operations complete with `errc::operation_canceled`.

        All outstanding operations complete with `errc::operation_canceled`.

        Check `ec == cond::canceled` for portable comparison.

        Check `ec == cond::canceled` for portable comparison.

    */

    */

    void cancel();

    void cancel();

    /** Get the local endpoint of the acceptor.

    /** Get the local endpoint of the acceptor.

        Returns the local address and port to which the acceptor is bound.

        Returns the local address and port to which the acceptor is bound.

        This is useful when binding to port 0 (ephemeral port) to discover

        This is useful when binding to port 0 (ephemeral port) to discover

        the OS-assigned port number. The endpoint is cached when listen()

        the OS-assigned port number. The endpoint is cached when listen()

        is called.

        is called.

        @return The local endpoint, or a default endpoint (0.0.0.0:0) if

        @return The local endpoint, or a default endpoint (0.0.0.0:0) if

            the acceptor is not listening.

            the acceptor is not listening.

        @par Thread Safety

        @par Thread Safety

        The cached endpoint value is set during listen() and cleared

        The cached endpoint value is set during listen() and cleared

        during close(). This function may be called concurrently with

        during close(). This function may be called concurrently with

        accept operations, but must not be called concurrently with

        accept operations, but must not be called concurrently with

        listen() or close().

        listen() or close().

    */

    */

    endpoint local_endpoint() const noexcept;

    endpoint local_endpoint() const noexcept;

    /** Set a socket option on the acceptor.

    /** Set a socket option on the acceptor.

        Applies a type-safe socket option to the underlying listening

        Applies a type-safe socket option to the underlying listening

        socket. The socket must be open (via `open()` or `listen()`).

        socket. The socket must be open (via `open()` or `listen()`).

        This is useful for setting options between `open()` and

        This is useful for setting options between `open()` and

        `listen()`, such as `socket_option::reuse_port`.

        `listen()`, such as `socket_option::reuse_port`.

        @par Example

        @par Example

        @code

        @code

        acc.open( tcp::v6() );

        acc.open( tcp::v6() );

        acc.set_option( socket_option::reuse_port( true ) );

        acc.set_option( socket_option::reuse_port( true ) );

        acc.bind( endpoint( ipv6_address::any(), 8080 ) );

        acc.bind( endpoint( ipv6_address::any(), 8080 ) );

        acc.listen();

        acc.listen();

        @endcode

        @endcode

        @param opt The option to set.

        @param opt The option to set.

        @throws std::logic_error if the acceptor is not open.

        @throws std::logic_error if the acceptor is not open.

        @throws std::system_error on failure.

        @throws std::system_error on failure.

    */

    */

    template<class Option>

    template<class Option>

    {

    {

                "set_option: acceptor not open" );

            Option::level(), Option::name(), opt.data(), opt.size() );

            Option::level(), Option::name(), opt.data(), opt.size());

                ec, "tcp_acceptor::set_option" );

    /** Get a socket option from the acceptor.

    /** Get a socket option from the acceptor.

        Retrieves the current value of a type-safe socket option.

        Retrieves the current value of a type-safe socket option.

        @par Example

        @par Example

        @code

        @code

        auto opt = acc.get_option<socket_option::reuse_address>();

        auto opt = acc.get_option<socket_option::reuse_address>();

        @endcode

        @endcode

        @return The current option value.

        @return The current option value.

        @throws std::logic_error if the acceptor is not open.

        @throws std::logic_error if the acceptor is not open.

        @throws std::system_error on failure.

        @throws std::system_error on failure.

    */

    */

    template<class Option>

    template<class Option>

    Option get_option() const

    Option get_option() const

    {

    {

        if (!is_open())

        if (!is_open())

            detail::throw_logic_error(

            detail::throw_logic_error("get_option: acceptor not open");

                "get_option: acceptor not open" );

        Option opt{};

        Option opt{};

        std::size_t sz = opt.size();

        std::size_t sz = opt.size();

        std::error_code ec = get().get_option(

        std::error_code ec =

            Option::level(), Option::name(), opt.data(), &sz );

            get().get_option(Option::level(), Option::name(), opt.data(), &sz);

        if (ec)

        if (ec)

            detail::throw_system_error(

            detail::throw_system_error(ec, "tcp_acceptor::get_option");

                ec, "tcp_acceptor::get_option" );

        opt.resize(sz);

        opt.resize( sz );

        return opt;

        return opt;

    }

    }

    struct implementation : io_object::implementation

    struct implementation : io_object::implementation

    {

    {

        virtual std::coroutine_handle<> accept(

        virtual std::coroutine_handle<> accept(

            std::coroutine_handle<>,

            std::coroutine_handle<>,

            capy::executor_ref,

            capy::executor_ref,

            std::stop_token,

            std::stop_token,

            std::error_code*,

            std::error_code*,

            io_object::implementation**) = 0;

            io_object::implementation**) = 0;

        /// Returns the cached local endpoint.

        /// Returns the cached local endpoint.

        virtual endpoint local_endpoint() const noexcept = 0;

        virtual endpoint local_endpoint() const noexcept = 0;

        /// Return true if the acceptor has a kernel resource open.

        /// Return true if the acceptor has a kernel resource open.

        virtual bool is_open() const noexcept = 0;

        virtual bool is_open() const noexcept = 0;

        /** Cancel any pending asynchronous operations.

        /** Cancel any pending asynchronous operations.

            All outstanding operations complete with operation_canceled error.

            All outstanding operations complete with operation_canceled error.

        */

        */

        virtual void cancel() noexcept = 0;

        virtual void cancel() noexcept = 0;

        /** Set a socket option.

        /** Set a socket option.

            @param level The protocol level.

            @param level The protocol level.

            @param optname The option name.

            @param optname The option name.

            @param data Pointer to the option value.

            @param data Pointer to the option value.

            @param size Size of the option value in bytes.

            @param size Size of the option value in bytes.

            @return Error code on failure, empty on success.

            @return Error code on failure, empty on success.

        */

        */

        virtual std::error_code set_option(

        virtual std::error_code set_option(

            int level, int optname,

            int level,

            void const* data, std::size_t size) noexcept = 0;

            int optname,

            void const* data,

            std::size_t size) noexcept = 0;

        /** Get a socket option.

        /** Get a socket option.

            @param level The protocol level.

            @param level The protocol level.

            @param optname The option name.

            @param optname The option name.

            @param data Pointer to receive the option value.

            @param data Pointer to receive the option value.

            @param size On entry, the size of the buffer. On exit,

            @param size On entry, the size of the buffer. On exit,

                the size of the option value.

                the size of the option value.

            @return Error code on failure, empty on success.

            @return Error code on failure, empty on success.

        */

        */

        virtual std::error_code get_option(

        virtual std::error_code

            int level, int optname,

        get_option(int level, int optname, void* data, std::size_t* size)

            void* data, std::size_t* size) const noexcept = 0;

            const noexcept = 0;

    };

    };

protected:

protected:

    /// Transfer accepted peer impl to the peer socket.

    /// Transfer accepted peer impl to the peer socket.

    static void

    static void

    {

    {

private:

private:

    {

    {

    }

    }

};

};

} // namespace boost::corosio

} // namespace boost::corosio

#endif

#endif