Diff coverage report for

//

//

// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)

// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)

//

//

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

#include <boost/corosio/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_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/concept/executor.hpp>

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

#include <system_error>

#include <system_error>

#include <concepts>

#include <concepts>

#include <coroutine>

#include <coroutine>

#include <cstddef>

#include <cstddef>

#include <memory>

#include <memory>

#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

    io_context ioc;

    io_context ioc;

    tcp_acceptor acc(ioc);

    tcp_acceptor acc(ioc);

    if (auto ec = acc.listen(endpoint(8080)))  // Bind to port 8080

    if (auto ec = acc.listen(endpoint(8080)))  // Bind to port 8080

        return ec;

        return ec;

    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

*/

*/

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::io_object_impl* peer_impl_ = nullptr;

        mutable io_object::io_object_impl* peer_impl_ = nullptr;

        {

        {

        {

        {

        }

        }

        {

        {

            // Transfer the accepted impl to the peer socket

            // Transfer the accepted impl to the peer socket

            // (acceptor is a friend of socket, so we can access impl_)

            // (acceptor is a friend of socket, so we can access impl_)

            {

            {

            }

            }

        }

        }

        template<typename Ex>

        template<typename Ex>

        auto await_suspend(

        auto await_suspend(

            std::coroutine_handle<> h,

            std::coroutine_handle<> h,

            Ex const& ex) -> std::coroutine_handle<>

            Ex const& ex) -> std::coroutine_handle<>

        {

        {

            return acc_.get().accept(h, ex, token_, &ec_, &peer_impl_);

            return acc_.get().accept(h, ex, token_, &ec_, &peer_impl_);

        }

        }

        template<typename Ex>

        template<typename Ex>

            std::coroutine_handle<> h,

            std::coroutine_handle<> h,

            Ex const& ex,

            Ex const& ex,

            std::stop_token token) -> std::coroutine_handle<>

            std::stop_token token) -> 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();

    ~tcp_acceptor();

    /** 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);

    /** 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)

    explicit tcp_acceptor(Ex const& ex)

        : tcp_acceptor(ex.context())

        : tcp_acceptor(ex.context())

    {

    {

    }

    }

    /** 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.

    */

    */

    {

    {

    /** Move assignment operator.

    /** Move assignment operator.

        Closes any existing acceptor and transfers ownership.

        Closes any existing acceptor and transfers ownership.

        The source and destination must share the same execution context.

        The source and destination must share the same execution context.

        @param other The acceptor to move from.

        @param other The acceptor to move from.

        @return Reference to this acceptor.

        @return Reference to this acceptor.

        @throws std::logic_error if the acceptors have different execution contexts.

        @throws std::logic_error if the acceptors have different execution contexts.

    */

    */

    {

    {

        {

        {

                    "cannot move tcp_acceptor across execution contexts");

                    "cannot move tcp_acceptor across execution contexts");

        }

        }

    }

    }

    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;

    /** Open, bind, and listen on an endpoint.

    /** Open, bind, and listen on an endpoint.

        Creates an IPv4 TCP socket, binds it to the specified endpoint,

        Creates an IPv4 TCP socket, binds it to the specified endpoint,

        and begins listening for incoming connections. This must be

        and begins listening for incoming connections. This must be

        called before initiating accept operations.

        called before initiating accept operations.

        @param ep The local endpoint to bind to. Use `endpoint(port)` to

        @param ep The local endpoint to bind to. Use `endpoint(port)` to

            bind to all interfaces on a specific port.

            bind to all interfaces on a specific port.

        @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 failure.

        @return An error code indicating success or the reason for failure.

            A default-constructed error code indicates success.

            A default-constructed error code indicates success.

        @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).

        @li `errc::operation_not_supported`: The acceptor service is

        @li `errc::operation_not_supported`: The acceptor service is

            unavailable in the context (POSIX only).

            unavailable in the context (POSIX only).

        @throws Nothing.

        @throws Nothing.

    */

    */

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

    [[nodiscard]] std::error_code listen(endpoint ep, 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.

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

    struct acceptor_impl : io_object_impl

    struct acceptor_impl : io_object_impl

    {

    {

        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_impl**) = 0;

            io_object_impl**) = 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;

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

    };

    };

private:

private:

    {

    {

    }

    }

};

};

} // namespace boost::corosio

} // namespace boost::corosio

#endif

#endif