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/detail/buffer_param.hpp>

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

#include <boost/corosio/endpoint.hpp>

#include <boost/corosio/endpoint.hpp>

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

#include <stop_token>

#include <type_traits>

#include <type_traits>

namespace boost::corosio {

namespace boost::corosio {

#if BOOST_COROSIO_HAS_IOCP && !defined(BOOST_COROSIO_MRDOCS)

#if BOOST_COROSIO_HAS_IOCP && !defined(BOOST_COROSIO_MRDOCS)

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

    };

    };

    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;

        /** Set a socket option.

        /** Set a socket option.

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

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

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

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

            @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 level,

            int optname,

            int optname,

            void const* data,

            void const* data,

            std::size_t size) noexcept = 0;

            std::size_t size) noexcept = 0;

        /** Get a socket option.

        /** Get a socket option.

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

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

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

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

            @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

        virtual std::error_code

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

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

            const noexcept = 0;

            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 a TCP socket and associates it with the platform

        Creates a TCP socket and associates it with the platform

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

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

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

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

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

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

        set before connecting.

        set before connecting.

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

    */

    */

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

    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 && !defined(BOOST_COROSIO_MRDOCS)

#if BOOST_COROSIO_HAS_IOCP && !defined(BOOST_COROSIO_MRDOCS)

        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.

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

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

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

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

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

        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::system_error if the socket needs to be opened

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

            and the open fails.

            and the open fails.

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

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

    /** Set a socket option.

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

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

        The option type encodes the protocol level and option name.

        The option type encodes the protocol level and option name.

        @par Example

        @par Example

        @code

        @code

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

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

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

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

        @endcode

        @endcode

        @param opt The option to set.

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

    */

    */

    template<class Option>

    template<class Option>

    {

    {

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

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

    /** Get a socket option.

    /** Get a socket option.

        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 nd = sock.get_option<socket_option::no_delay>();

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

        if ( nd.value() )

        if ( nd.value() )

            // Nagle's algorithm is disabled

            // Nagle's algorithm is disabled

        @endcode

        @endcode

        @return The current option value.

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

    */

    */

    template<class Option>

    template<class Option>

    {

    {

        std::error_code ec =

        std::error_code ec =

    }

    }

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

        @par Thread Safety

        @par Thread Safety

        The cached endpoint value is set during connect/accept completion

        The cached endpoint value is set during connect/accept completion

        and cleared during close(). This function may be called concurrently

        and cleared during close(). This function may be called concurrently

        with I/O operations, but must not be called concurrently with

        with I/O operations, but must not be called concurrently with

        connect(), accept(), or close().

        connect(), accept(), or close().

    */

    */

    endpoint local_endpoint() const noexcept;

    endpoint local_endpoint() const noexcept;

    /** Get the remote endpoint of the socket.

    /** Get the remote endpoint of the socket.

        Returns the remote address and port to which the socket is connected.

        Returns the remote address and port to which the socket is connected.

        The endpoint is cached when the connection is established.

        The endpoint is cached when the connection is established.

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

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

            the socket is not connected.

            the socket is not connected.

        @par Thread Safety

        @par Thread Safety

        The cached endpoint value is set during connect/accept completion

        The cached endpoint value is set during connect/accept completion

        and cleared during close(). This function may be called concurrently

        and cleared during close(). This function may be called concurrently

        with I/O operations, but must not be called concurrently with

        with I/O operations, but must not be called concurrently with

        connect(), accept(), or close().

        connect(), accept(), or close().

    */

    */

    endpoint remote_endpoint() const noexcept;

    endpoint remote_endpoint() const noexcept;

protected:

protected:

    explicit tcp_socket(handle h) noexcept : io_object(std::move(h)) {}

    explicit tcp_socket(handle h) noexcept : io_object(std::move(h)) {}

private:

private:

    friend class tcp_acceptor;

    friend class tcp_acceptor;

    /// Open the socket for the given protocol triple.

    /// Open the socket for the given protocol triple.

    void open_for_family(int family, int type, int protocol);

    void open_for_family(int family, int type, int protocol);

    {

    {

    }

    }

};

};

} // namespace boost::corosio

} // namespace boost::corosio

#endif

#endif