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_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_stream.hpp>

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

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

    /** Options for SO_LINGER socket option. */

    struct linger_options

    struct linger_options

    {

    {

        bool enabled = false;

        bool enabled = false;

        int timeout = 0;  // seconds

        int timeout = 0;  // seconds

    };

    };

    struct socket_impl : io_stream_impl

    struct socket_impl : io_stream_impl

    {

    {

        virtual void connect(

        virtual void 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

        // Socket options

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

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

        virtual bool no_delay(std::error_code& ec) const 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 std::error_code set_keep_alive(bool value) noexcept = 0;

        virtual bool keep_alive(std::error_code& ec) const 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;

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

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

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

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

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

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

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

        virtual std::error_code set_linger(bool enabled, int timeout) noexcept = 0;

        virtual std::error_code set_linger(bool enabled, int timeout) noexcept = 0;

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

        virtual linger_options linger(std::error_code& ec) 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_;

        {

        {

        {

        {

        }

        }

        {

        {

        }

        }

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

        {

        {

            s_.get().connect(h, ex, endpoint_, token_, &ec_);

            s_.get().connect(h, ex, endpoint_, token_, &ec_);

            return std::noop_coroutine();

            return std::noop_coroutine();

        }

        }

        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 socket if open, cancelling any pending operations.

        Closes the socket if open, cancelling any pending operations.

    */

    */

    ~tcp_socket();

    ~tcp_socket();

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

    explicit tcp_socket(Ex const& ex)

        : tcp_socket(ex.context())

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

    */

    */

    {

    {

    /** Move assignment operator.

    /** Move assignment operator.

        Closes any existing socket and transfers ownership.

        Closes any existing socket 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 socket to move from.

        @param other The socket to move from.

        @return Reference to this socket.

        @return Reference to this socket.

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

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

    */

    */

    {

    {

        {

        {

                    "cannot move socket across execution contexts");

                    "cannot move socket across execution contexts");

        }

        }

    }

    }

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

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

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

        I/O operations.

        I/O operations.

        @throws std::system_error on failure.

        @throws std::system_error on failure.

    */

    */

    void open();

    void open();

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

    */

    */

    {

    {

    }

    }

    /** Initiate an asynchronous connect operation.

    /** Initiate an asynchronous connect operation.

        Connects the socket to the specified remote endpoint. The socket

        Connects the socket to the specified remote endpoint. The socket

        must be open before calling this function.

        must be open 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 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::logic_error if the socket is not open.

        @par Preconditions

        @par Preconditions

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

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

        @par Example

        @par Example

        @code

        @code

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

    //--------------------------------------------------------------------------

    //--------------------------------------------------------------------------

    //

    //

    // Socket Options

    // Socket Options

    //

    //

    //--------------------------------------------------------------------------

    //--------------------------------------------------------------------------

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

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

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

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

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

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

        at the potential cost of increased network traffic.

        at the potential cost of increased network traffic.

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

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

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

    */

    */

    void set_no_delay(bool value);

    void set_no_delay(bool value);

    /** Get the current TCP_NODELAY setting.

    /** Get the current TCP_NODELAY setting.

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

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

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

    */

    */

    bool no_delay() const;

    bool no_delay() const;

    /** Enable or disable SO_KEEPALIVE.

    /** Enable or disable SO_KEEPALIVE.

        When enabled, the socket will periodically send keepalive probes

        When enabled, the socket will periodically send keepalive probes

        to detect if the peer is still reachable.

        to detect if the peer is still reachable.

        @param value `true` to enable keepalive probes.

        @param value `true` to enable keepalive probes.

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

    */

    */

    void set_keep_alive(bool value);

    void set_keep_alive(bool value);

    /** Get the current SO_KEEPALIVE setting.

    /** Get the current SO_KEEPALIVE setting.

        @return `true` if keepalive is enabled.

        @return `true` if keepalive is enabled.

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

    */

    */

    bool keep_alive() const;

    bool keep_alive() const;

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

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

        @param size The desired receive buffer size in bytes.

        @param size The desired receive buffer size in bytes.

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

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

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

    */

    */

    void set_receive_buffer_size(int size);

    void set_receive_buffer_size(int size);

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

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

        @return The current receive buffer size in bytes.

        @return The current receive buffer size in bytes.

        @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 receive_buffer_size() const;

    int receive_buffer_size() const;

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

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

        @param size The desired send buffer size in bytes.

        @param size The desired send buffer size in bytes.

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

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

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

    */

    */

    void set_send_buffer_size(int size);

    void set_send_buffer_size(int size);

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

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

        @return The current send buffer size in bytes.

        @return The current send buffer size in bytes.

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

    int send_buffer_size() const;

    /** Set the SO_LINGER option.

    /** Set the SO_LINGER option.

        Controls behavior when closing a socket with unsent data.

        Controls behavior when closing a socket with unsent data.

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

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

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

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

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

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

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

    */

    */

    void set_linger(bool enabled, int timeout);

    void set_linger(bool enabled, int timeout);

    /** Get the current SO_LINGER setting.

    /** Get the current SO_LINGER setting.

        @return The current linger options.

        @return The current linger options.

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

    linger_options linger() const;

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

private:

private:

    friend class tcp_acceptor;

    friend class tcp_acceptor;

    {

    {

    }

    }

};

};

} // namespace boost::corosio

} // namespace boost::corosio