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_SOCKET_HPP

#ifndef BOOST_COROSIO_TCP_SOCKET_HPP

#define BOOST_COROSIO_TCP_SOCKET_HPP

#define BOOST_COROSIO_TCP_SOCKET_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/except.hpp>

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

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

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

#include <boost/capy/io_result.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/corosio/io_buffer_param.hpp>

#include <boost/corosio/io_buffer_param.hpp>

#include <boost/corosio/endpoint.hpp>

#include <boost/corosio/endpoint.hpp>

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

#if BOOST_COROSIO_HAS_IOCP

#if BOOST_COROSIO_HAS_IOCP

using native_handle_type = std::uintptr_t; // SOCKET

using native_handle_type = std::uintptr_t; // SOCKET

#else

#else

using native_handle_type = int;

using native_handle_type = int;

#endif

#endif

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

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

    This class provides asynchronous TCP socket operations that return

    This class provides asynchronous TCP socket operations that return

    awaitable types. Each operation participates in the affine awaitable

    awaitable types. Each operation participates in the affine awaitable

    protocol, ensuring coroutines resume on the correct executor.

    protocol, ensuring coroutines resume on the correct executor.

    The socket must be opened before performing I/O operations. Operations

    The socket must be opened before performing I/O operations. Operations

    support cancellation through `std::stop_token` via the affine protocol,

    support cancellation through `std::stop_token` via the affine protocol,

    or explicitly through the `cancel()` member function.

    or explicitly through the `cancel()` member function.

    @par Thread Safety

    @par Thread Safety

    Distinct objects: Safe.@n

    Distinct objects: Safe.@n

    Shared objects: Unsafe. A socket must not have concurrent operations

    Shared objects: Unsafe. A socket must not have concurrent operations

    of the same type (e.g., two simultaneous reads). One read and one

    of the same type (e.g., two simultaneous reads). One read and one

    write may be in flight simultaneously.

    write may be in flight simultaneously.

    @par Semantics

    @par Semantics

    Wraps the platform TCP/IP stack. Operations dispatch to

    Wraps the platform TCP/IP stack. Operations dispatch to

    OS socket APIs via the io_context reactor (epoll, IOCP,

    OS socket APIs via the io_context reactor (epoll, IOCP,

    kqueue). Satisfies @ref capy::Stream.

    kqueue). Satisfies @ref capy::Stream.

    @par Example

    @par Example

    @code

    @code

    io_context ioc;

    io_context ioc;

    tcp_socket s(ioc);

    tcp_socket s(ioc);

    s.open();

    s.open();

    // Using structured bindings

    // Using structured bindings

    auto [ec] = co_await s.connect(

    auto [ec] = co_await s.connect(

        endpoint(ipv4_address::loopback(), 8080));

        endpoint(ipv4_address::loopback(), 8080));

    if (ec)

    if (ec)

        co_return;

        co_return;

    char buf[1024];

    char buf[1024];

    auto [read_ec, n] = co_await s.read_some(

    auto [read_ec, n] = co_await s.read_some(

        capy::mutable_buffer(buf, sizeof(buf)));

        capy::mutable_buffer(buf, sizeof(buf)));

    @endcode

    @endcode

*/

*/

class BOOST_COROSIO_DECL tcp_socket : public io_stream

class BOOST_COROSIO_DECL tcp_socket : public io_stream

{

{

public:

public:

    /** Different ways a socket may be shutdown. */

    /** Different ways a socket may be shutdown. */

    enum shutdown_type

    enum shutdown_type

    {

    {

        shutdown_receive,

        shutdown_receive,

        shutdown_send,

        shutdown_send,

        shutdown_both

        shutdown_both

    };

    };

    /** Options for SO_LINGER socket option. */

    struct linger_options

    {

        bool enabled = false;

        int timeout  = 0; // seconds

    };

    struct implementation : io_stream::implementation

    struct implementation : io_stream::implementation

    {

    {

        virtual std::coroutine_handle<> connect(

        virtual std::coroutine_handle<> connect(

            std::coroutine_handle<>,

            std::coroutine_handle<>,

            capy::executor_ref,

            capy::executor_ref,

            endpoint,

            endpoint,

            std::stop_token,

            std::stop_token,

            std::error_code*) = 0;

            std::error_code*) = 0;

        virtual std::error_code shutdown(shutdown_type) noexcept = 0;

        virtual std::error_code shutdown(shutdown_type) noexcept = 0;

        virtual native_handle_type native_handle() const noexcept = 0;

        virtual native_handle_type native_handle() const noexcept = 0;

        /** Request cancellation of pending asynchronous operations.

        /** Request cancellation of pending asynchronous operations.

            All outstanding operations complete with operation_canceled error.

            All outstanding operations complete with operation_canceled error.

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

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

        */

        */

        virtual void cancel() noexcept = 0;

        virtual void cancel() noexcept = 0;

        // Socket options

        /** Set a socket option.

        virtual std::error_code set_no_delay(bool value) noexcept = 0;

        virtual bool no_delay(std::error_code& ec) const noexcept = 0;

        virtual std::error_code set_keep_alive(bool value) noexcept = 0;

        virtual bool keep_alive(std::error_code& ec) const noexcept = 0;

        virtual std::error_code set_receive_buffer_size(int size) noexcept  = 0;

            @param level The protocol level (e.g. `SOL_SOCKET`).

        virtual int receive_buffer_size(std::error_code& ec) const noexcept = 0;

            @param optname The option name (e.g. `SO_KEEPALIVE`).

            @param data Pointer to the option value.

            @param size Size of the option value in bytes.

            @return Error code on failure, empty on success.

        */

        virtual std::error_code set_option(

            int level, int optname,

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

        virtual std::error_code set_send_buffer_size(int size) noexcept  = 0;

        /** Get a socket option.

        virtual int send_buffer_size(std::error_code& ec) const noexcept = 0;

        virtual std::error_code

            @param level The protocol level (e.g. `SOL_SOCKET`).

        set_linger(bool enabled, int timeout) noexcept                    = 0;

            @param optname The option name (e.g. `SO_KEEPALIVE`).

        virtual linger_options linger(std::error_code& ec) const noexcept = 0;

            @param data Pointer to receive the option value.

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

                the size of the option value.

            @return Error code on failure, empty on success.

        */

        virtual std::error_code get_option(

            int level, int optname,

            void* data, std::size_t* size) const noexcept = 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;

        /// Returns the cached remote endpoint.

        /// Returns the cached remote endpoint.

        virtual endpoint remote_endpoint() const noexcept = 0;

        virtual endpoint remote_endpoint() const noexcept = 0;

    };

    };

    struct connect_awaitable

    struct connect_awaitable

    {

    {

        tcp_socket& s_;

        tcp_socket& s_;

        endpoint endpoint_;

        endpoint endpoint_;

        std::stop_token token_;

        std::stop_token token_;

        mutable std::error_code ec_;

        mutable std::error_code ec_;

        {

        {

        {

        {

        }

        }

        {

        {

        }

        }

            -> std::coroutine_handle<>

            -> std::coroutine_handle<>

        {

        {

        }

        }

    };

    };

public:

public:

    /** Destructor.

    /** Destructor.

        Closes the socket if open, cancelling any pending operations.

        Closes the socket if open, cancelling any pending operations.

    */

    */

    ~tcp_socket() override;

    ~tcp_socket() override;

    /** Construct a socket from an execution context.

    /** Construct a socket from an execution context.

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

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

    */

    */

    explicit tcp_socket(capy::execution_context& ctx);

    explicit tcp_socket(capy::execution_context& ctx);

    /** Construct a socket from an executor.

    /** Construct a socket from an executor.

        The socket is associated with the executor's context.

        The socket is associated with the executor's context.

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

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

    */

    */

    template<class Ex>

    template<class Ex>

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

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

        capy::Executor<Ex>

        capy::Executor<Ex>

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

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

    {

    {

    }

    }

    /** Move constructor.

    /** Move constructor.

        Transfers ownership of the socket resources.

        Transfers ownership of the socket resources.

        @param other The socket to move from.

        @param other The socket to move from.

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

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

        @pre @p other is not referenced as a peer in any outstanding

        @pre @p other is not referenced as a peer in any outstanding

            accept awaitable.

            accept awaitable.

        @pre The execution context associated with @p other must

        @pre The execution context associated with @p other must

            outlive this socket.

            outlive this socket.

    */

    */

    /** Move assignment operator.

    /** Move assignment operator.

        Closes any existing socket and transfers ownership.

        Closes any existing socket and transfers ownership.

        @param other The socket to move from.

        @param other The socket 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 Neither `*this` nor @p other is referenced as a peer in

        @pre Neither `*this` nor @p other is referenced as a peer in

            any outstanding accept awaitable.

            any outstanding accept awaitable.

        @pre The execution context associated with @p other must

        @pre The execution context associated with @p other must

            outlive this socket.

            outlive this socket.

        @return Reference to this socket.

        @return Reference to this socket.

    */

    */

    {

    {

        {

        {

        }

        }

    }

    }

    tcp_socket(tcp_socket const&)            = delete;

    tcp_socket(tcp_socket const&)            = delete;

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

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

    /** Open the socket.

    /** Open the socket.

        Creates an IPv4 TCP socket and associates it with the platform

        Creates a TCP socket and associates it with the platform

        reactor (IOCP on Windows). This must be called before initiating

        reactor (IOCP on Windows). Calling @ref connect on a closed

        I/O operations.

        socket opens it automatically with the endpoint's address family,

        so explicit `open()` is only needed when socket options must be

        set before connecting.

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

            `tcp::v4()`.

        @throws std::system_error on failure.

        @throws std::system_error on failure.

    */

    */

    void open();

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

    /** Close the socket.

    /** Close the socket.

        Releases socket resources. Any pending operations complete

        Releases socket resources. Any pending operations complete

        with `errc::operation_canceled`.

        with `errc::operation_canceled`.

    */

    */

    void close();

    void close();

    /** Check if the socket is open.

    /** Check if the socket is open.

        @return `true` if the socket is open and ready for operations.

        @return `true` if the socket is open and ready for operations.

    */

    */

    {

    {

#if BOOST_COROSIO_HAS_IOCP

#if BOOST_COROSIO_HAS_IOCP

        return h_ && get().native_handle() != ~native_handle_type(0);

        return h_ && get().native_handle() != ~native_handle_type(0);

#else

#else

#endif

#endif

    }

    }

    /** Initiate an asynchronous connect operation.

    /** Initiate an asynchronous connect operation.

        Connects the socket to the specified remote endpoint. The socket

        If the socket is not already open, it is opened automatically

        must be open before calling this function.

        using the address family of @p ep (IPv4 or IPv6). If the socket

        is already open, the existing file descriptor is used as-is.

        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 ep The remote endpoint to connect to.

        @param ep The remote endpoint to connect to.

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

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

            Returns success (default error_code) on successful connection,

            Returns success (default error_code) on successful connection,

            or an error code on failure including:

            or an error code on failure including:

            - connection_refused: No server listening at endpoint

            - connection_refused: No server listening at endpoint

            - timed_out: Connection attempt timed out

            - timed_out: Connection attempt timed out

            - network_unreachable: No route to host

            - network_unreachable: No route to host

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

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

        @throws std::system_error if the socket needs to be opened

            and the open fails.

        The socket must be open (`is_open() == true`).

        @par Preconditions

        @par Preconditions

        This socket must outlive the returned awaitable.

        This socket must outlive the returned awaitable.

        @par Example

        @par Example

        @code

        @code

        // Socket opened automatically with correct address family:

        auto [ec] = co_await s.connect(endpoint);

        auto [ec] = co_await s.connect(endpoint);

        if (ec) { ... }

        if (ec) { ... }

        @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 native socket handle.

    /** Get the native socket handle.

        Returns the underlying platform-specific socket descriptor.

        Returns the underlying platform-specific socket descriptor.

        On POSIX systems this is an `int` file descriptor.

        On POSIX systems this is an `int` file descriptor.

        On Windows this is a `SOCKET` handle.

        On Windows this is a `SOCKET` handle.

        @return The native socket handle, or -1/INVALID_SOCKET if not open.

        @return The native socket handle, or -1/INVALID_SOCKET if not open.

        @par Preconditions

        @par Preconditions

        None. May be called on closed sockets.

        None. May be called on closed sockets.

    */

    */

    native_handle_type native_handle() const noexcept;

    native_handle_type native_handle() const noexcept;

    /** Disable sends or receives on the socket.

    /** Disable sends or receives on the socket.

        TCP connections are full-duplex: each direction (send and receive)

        TCP connections are full-duplex: each direction (send and receive)

        operates independently. This function allows you to close one or

        operates independently. This function allows you to close one or

        both directions without destroying the socket.

        both directions without destroying the socket.

        @li @ref shutdown_send sends a TCP FIN packet to the peer,

        @li @ref shutdown_send sends a TCP FIN packet to the peer,

            signaling that you have no more data to send. You can still

            signaling that you have no more data to send. You can still

            receive data until the peer also closes their send direction.

            receive data until the peer also closes their send direction.

            This is the most common use case, typically called before

            This is the most common use case, typically called before

            close() to ensure graceful connection termination.

            close() to ensure graceful connection termination.

        @li @ref shutdown_receive disables reading on the socket. This

        @li @ref shutdown_receive disables reading on the socket. This

            does NOT send anything to the peer - they are not informed

            does NOT send anything to the peer - they are not informed

            and may continue sending data. Subsequent reads will fail

            and may continue sending data. Subsequent reads will fail

            or return end-of-file. Incoming data may be discarded or

            or return end-of-file. Incoming data may be discarded or

            buffered depending on the operating system.

            buffered depending on the operating system.

        @li @ref shutdown_both combines both effects: sends a FIN and

        @li @ref shutdown_both combines both effects: sends a FIN and

            disables reading.

            disables reading.

        When the peer shuts down their send direction (sends a FIN),

        When the peer shuts down their send direction (sends a FIN),

        subsequent read operations will complete with `capy::cond::eof`.

        subsequent read operations will complete with `capy::cond::eof`.

        Use the portable condition test rather than comparing error

        Use the portable condition test rather than comparing error

        codes directly:

        codes directly:

        @code

        @code

        auto [ec, n] = co_await sock.read_some(buffer);

        auto [ec, n] = co_await sock.read_some(buffer);

        if (ec == capy::cond::eof)

        if (ec == capy::cond::eof)

        {

        {

            // Peer closed their send direction

            // Peer closed their send direction

        }

        }

        @endcode

        @endcode

        Any error from the underlying system call is silently discarded

        Any error from the underlying system call is silently discarded

        because it is unlikely to be helpful.

        because it is unlikely to be helpful.

        @param what Determines what operations will no longer be allowed.

        @param what Determines what operations will no longer be allowed.

    */

    */

    void shutdown(shutdown_type what);

    void shutdown(shutdown_type what);

    //

    /** Set a socket option.

    // Socket Options

    //

    /** Enable or disable TCP_NODELAY (disable Nagle's algorithm).

        When enabled, segments are sent as soon as possible even if

        there is only a small amount of data. This reduces latency

        at the potential cost of increased network traffic.

        @param value `true` to disable Nagle's algorithm (enable no-delay).

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

        @throws std::system_error on failure.

    */

    void set_no_delay(bool value);

    /** Get the current TCP_NODELAY setting.

        @return `true` if Nagle's algorithm is disabled.

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

        @throws std::system_error on failure.

    */

    bool no_delay() const;

    /** Enable or disable SO_KEEPALIVE.

        When enabled, the socket will periodically send keepalive probes

        to detect if the peer is still reachable.

        @param value `true` to enable keepalive probes.

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

        @throws std::system_error on failure.

    */

    void set_keep_alive(bool value);

    /** Get the current SO_KEEPALIVE setting.

        @return `true` if keepalive is enabled.

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

        @throws std::system_error on failure.

    */

    bool keep_alive() const;

    /** Set the receive buffer size (SO_RCVBUF).

        @param size The desired receive buffer size in bytes.

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

        @throws std::system_error on failure.

        @note The operating system may adjust the actual buffer size.

    */

    void set_receive_buffer_size(int size);

    /** Get the receive buffer size (SO_RCVBUF).

        @return The current receive buffer size in bytes.

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

        @throws std::system_error on failure.

    */

    int receive_buffer_size() const;

    /** Set the send buffer size (SO_SNDBUF).

        @param size The desired send buffer size in bytes.

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

        @throws std::system_error on failure.

        @note The operating system may adjust the actual buffer size.

        Applies a type-safe socket option to the underlying socket.

    */

        The option type encodes the protocol level and option name.

    void set_send_buffer_size(int size);

    /** Get the send buffer size (SO_SNDBUF).

        @par Example

        @code

        sock.set_option( socket_option::no_delay( true ) );

        sock.set_option( socket_option::receive_buffer_size( 65536 ) );

        @endcode

        @return The current send buffer size in bytes.

        @param opt The option to set.

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

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

        @throws std::system_error on failure.

        @throws std::system_error on failure.

    */

    */

    int send_buffer_size() const;

    template<class Option>

    /** Set the SO_LINGER option.

    {

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

        @param enabled If `true`, close() will block until data is sent

    /** Get a socket option.

            or the timeout expires. If `false`, close() returns immediately.

        @param timeout The linger timeout in seconds (only used if enabled).

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

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

        @throws std::system_error on failure.

    */

    void set_linger(bool enabled, int timeout);

    /** Get the current SO_LINGER setting.

        @par Example

        @code

        auto nd = sock.get_option<socket_option::no_delay>();

        if ( nd.value() )

            // Nagle's algorithm is disabled

        @endcode

        @return The current linger options.

        @return The current option value.

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

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

        @throws std::system_error on failure.

        @throws std::system_error on failure.

    */

    */

    linger_options linger() const;

    template<class Option>

    {

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

    }

    /** Get the local endpoint of the socket.

    /** Get the local endpoint of the socket.

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

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

        For a connected socket, this is the local side of the connection.

        For a connected socket, this is the local side of the connection.

        The endpoint is cached when the connection is established.

        The endpoint is cached when the connection is established.

        @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 socket is not connected.

            the socket is not connected.