1   
//
1   
//
2   
// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
2   
// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
3   
// Copyright (c) 2026 Steve Gerbino
3   
// Copyright (c) 2026 Steve Gerbino
4   
//
4   
//
5   
// Distributed under the Boost Software License, Version 1.0. (See accompanying
5   
// Distributed under the Boost Software License, Version 1.0. (See accompanying
6   
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6   
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7   
//
7   
//
8   
// Official repository: https://github.com/cppalliance/corosio
8   
// Official repository: https://github.com/cppalliance/corosio
9   
//
9   
//
10  
10  
11   
#ifndef BOOST_COROSIO_TCP_SOCKET_HPP
11   
#ifndef BOOST_COROSIO_TCP_SOCKET_HPP
12   
#define BOOST_COROSIO_TCP_SOCKET_HPP
12   
#define BOOST_COROSIO_TCP_SOCKET_HPP
13  
13  
14   
#include <boost/corosio/detail/config.hpp>
14   
#include <boost/corosio/detail/config.hpp>
15   
#include <boost/corosio/detail/platform.hpp>
15   
#include <boost/corosio/detail/platform.hpp>
16   
#include <boost/corosio/detail/except.hpp>
16   
#include <boost/corosio/detail/except.hpp>
17   
#include <boost/corosio/io/io_stream.hpp>
17   
#include <boost/corosio/io/io_stream.hpp>
18   
#include <boost/capy/io_result.hpp>
18   
#include <boost/capy/io_result.hpp>
19 - 
#include <boost/corosio/io_buffer_param.hpp>
19 + 
#include <boost/corosio/detail/buffer_param.hpp>
20   
#include <boost/corosio/endpoint.hpp>
20   
#include <boost/corosio/endpoint.hpp>
21   
#include <boost/corosio/tcp.hpp>
21   
#include <boost/corosio/tcp.hpp>
22   
#include <boost/capy/ex/executor_ref.hpp>
22   
#include <boost/capy/ex/executor_ref.hpp>
23   
#include <boost/capy/ex/execution_context.hpp>
23   
#include <boost/capy/ex/execution_context.hpp>
24   
#include <boost/capy/ex/io_env.hpp>
24   
#include <boost/capy/ex/io_env.hpp>
25   
#include <boost/capy/concept/executor.hpp>
25   
#include <boost/capy/concept/executor.hpp>
26  
26  
27   
#include <system_error>
27   
#include <system_error>
28  
28  
29   
#include <concepts>
29   
#include <concepts>
30   
#include <coroutine>
30   
#include <coroutine>
31 - 
#include <memory>
 
32   
#include <cstddef>
31   
#include <cstddef>
33   
#include <stop_token>
32   
#include <stop_token>
34   
#include <type_traits>
33   
#include <type_traits>
35  
34  
36   
namespace boost::corosio {
35   
namespace boost::corosio {
37  
36  
38   
#if BOOST_COROSIO_HAS_IOCP && !defined(BOOST_COROSIO_MRDOCS)
37   
#if BOOST_COROSIO_HAS_IOCP && !defined(BOOST_COROSIO_MRDOCS)
39   
using native_handle_type = std::uintptr_t; // SOCKET
38   
using native_handle_type = std::uintptr_t; // SOCKET
40   
#else
39   
#else
41   
using native_handle_type = int;
40   
using native_handle_type = int;
42   
#endif
41   
#endif
43  
42  
44   
/** An asynchronous TCP socket for coroutine I/O.
43   
/** An asynchronous TCP socket for coroutine I/O.
45  
44  
46   
    This class provides asynchronous TCP socket operations that return
45   
    This class provides asynchronous TCP socket operations that return
47   
    awaitable types. Each operation participates in the affine awaitable
46   
    awaitable types. Each operation participates in the affine awaitable
48   
    protocol, ensuring coroutines resume on the correct executor.
47   
    protocol, ensuring coroutines resume on the correct executor.
49  
48  
50   
    The socket must be opened before performing I/O operations. Operations
49   
    The socket must be opened before performing I/O operations. Operations
51   
    support cancellation through `std::stop_token` via the affine protocol,
50   
    support cancellation through `std::stop_token` via the affine protocol,
52   
    or explicitly through the `cancel()` member function.
51   
    or explicitly through the `cancel()` member function.
53  
52  
54   
    @par Thread Safety
53   
    @par Thread Safety
55   
    Distinct objects: Safe.@n
54   
    Distinct objects: Safe.@n
56   
    Shared objects: Unsafe. A socket must not have concurrent operations
55   
    Shared objects: Unsafe. A socket must not have concurrent operations
57   
    of the same type (e.g., two simultaneous reads). One read and one
56   
    of the same type (e.g., two simultaneous reads). One read and one
58   
    write may be in flight simultaneously.
57   
    write may be in flight simultaneously.
59  
58  
60   
    @par Semantics
59   
    @par Semantics
61   
    Wraps the platform TCP/IP stack. Operations dispatch to
60   
    Wraps the platform TCP/IP stack. Operations dispatch to
62   
    OS socket APIs via the io_context reactor (epoll, IOCP,
61   
    OS socket APIs via the io_context reactor (epoll, IOCP,
63   
    kqueue). Satisfies @ref capy::Stream.
62   
    kqueue). Satisfies @ref capy::Stream.
64  
63  
65   
    @par Example
64   
    @par Example
66   
    @code
65   
    @code
67   
    io_context ioc;
66   
    io_context ioc;
68   
    tcp_socket s(ioc);
67   
    tcp_socket s(ioc);
69   
    s.open();
68   
    s.open();
70  
69  
71   
    // Using structured bindings
70   
    // Using structured bindings
72   
    auto [ec] = co_await s.connect(
71   
    auto [ec] = co_await s.connect(
73   
        endpoint(ipv4_address::loopback(), 8080));
72   
        endpoint(ipv4_address::loopback(), 8080));
74   
    if (ec)
73   
    if (ec)
75   
        co_return;
74   
        co_return;
76  
75  
77   
    char buf[1024];
76   
    char buf[1024];
78   
    auto [read_ec, n] = co_await s.read_some(
77   
    auto [read_ec, n] = co_await s.read_some(
79   
        capy::mutable_buffer(buf, sizeof(buf)));
78   
        capy::mutable_buffer(buf, sizeof(buf)));
80   
    @endcode
79   
    @endcode
81   
*/
80   
*/
82   
class BOOST_COROSIO_DECL tcp_socket : public io_stream
81   
class BOOST_COROSIO_DECL tcp_socket : public io_stream
83   
{
82   
{
84   
public:
83   
public:
85   
    /** Different ways a socket may be shutdown. */
84   
    /** Different ways a socket may be shutdown. */
86   
    enum shutdown_type
85   
    enum shutdown_type
87   
    {
86   
    {
88   
        shutdown_receive,
87   
        shutdown_receive,
89   
        shutdown_send,
88   
        shutdown_send,
90   
        shutdown_both
89   
        shutdown_both
91   
    };
90   
    };
92  
91  
93   
    struct implementation : io_stream::implementation
92   
    struct implementation : io_stream::implementation
94   
    {
93   
    {
95   
        virtual std::coroutine_handle<> connect(
94   
        virtual std::coroutine_handle<> connect(
96   
            std::coroutine_handle<>,
95   
            std::coroutine_handle<>,
97   
            capy::executor_ref,
96   
            capy::executor_ref,
98   
            endpoint,
97   
            endpoint,
99   
            std::stop_token,
98   
            std::stop_token,
100   
            std::error_code*) = 0;
99   
            std::error_code*) = 0;
101  
100  
102   
        virtual std::error_code shutdown(shutdown_type) noexcept = 0;
101   
        virtual std::error_code shutdown(shutdown_type) noexcept = 0;
103  
102  
104   
        virtual native_handle_type native_handle() const noexcept = 0;
103   
        virtual native_handle_type native_handle() const noexcept = 0;
105  
104  
106   
        /** Request cancellation of pending asynchronous operations.
105   
        /** Request cancellation of pending asynchronous operations.
107  
106  
108   
            All outstanding operations complete with operation_canceled error.
107   
            All outstanding operations complete with operation_canceled error.
109   
            Check `ec == cond::canceled` for portable comparison.
108   
            Check `ec == cond::canceled` for portable comparison.
110   
        */
109   
        */
111   
        virtual void cancel() noexcept = 0;
110   
        virtual void cancel() noexcept = 0;
112  
111  
113   
        /** Set a socket option.
112   
        /** Set a socket option.
114  
113  
115   
            @param level The protocol level (e.g. `SOL_SOCKET`).
114   
            @param level The protocol level (e.g. `SOL_SOCKET`).
116   
            @param optname The option name (e.g. `SO_KEEPALIVE`).
115   
            @param optname The option name (e.g. `SO_KEEPALIVE`).
117   
            @param data Pointer to the option value.
116   
            @param data Pointer to the option value.
118   
            @param size Size of the option value in bytes.
117   
            @param size Size of the option value in bytes.
119   
            @return Error code on failure, empty on success.
118   
            @return Error code on failure, empty on success.
120   
        */
119   
        */
121   
        virtual std::error_code set_option(
120   
        virtual std::error_code set_option(
122 - 
            int level, int optname,
121 + 
            int level,
123 - 
            void const* data, std::size_t size) noexcept = 0;
122 + 
            int optname,
 
123 + 
            void const* data,
 
124 + 
            std::size_t size) noexcept = 0;
124  
125  
125   
        /** Get a socket option.
126   
        /** Get a socket option.
126  
127  
127   
            @param level The protocol level (e.g. `SOL_SOCKET`).
128   
            @param level The protocol level (e.g. `SOL_SOCKET`).
128   
            @param optname The option name (e.g. `SO_KEEPALIVE`).
129   
            @param optname The option name (e.g. `SO_KEEPALIVE`).
129   
            @param data Pointer to receive the option value.
130   
            @param data Pointer to receive the option value.
130   
            @param size On entry, the size of the buffer. On exit,
131   
            @param size On entry, the size of the buffer. On exit,
131   
                the size of the option value.
132   
                the size of the option value.
132   
            @return Error code on failure, empty on success.
133   
            @return Error code on failure, empty on success.
133   
        */
134   
        */
134 - 
        virtual std::error_code get_option(
135 + 
        virtual std::error_code
135 - 
            int level, int optname,
136 + 
        get_option(int level, int optname, void* data, std::size_t* size)
136 - 
            void* data, std::size_t* size) const noexcept = 0;
137 + 
            const noexcept = 0;
137  
138  
138   
        /// Returns the cached local endpoint.
139   
        /// Returns the cached local endpoint.
139   
        virtual endpoint local_endpoint() const noexcept = 0;
140   
        virtual endpoint local_endpoint() const noexcept = 0;
140  
141  
141   
        /// Returns the cached remote endpoint.
142   
        /// Returns the cached remote endpoint.
142   
        virtual endpoint remote_endpoint() const noexcept = 0;
143   
        virtual endpoint remote_endpoint() const noexcept = 0;
143   
    };
144   
    };
144  
145  
145   
    struct connect_awaitable
146   
    struct connect_awaitable
146   
    {
147   
    {
147   
        tcp_socket& s_;
148   
        tcp_socket& s_;
148   
        endpoint endpoint_;
149   
        endpoint endpoint_;
149   
        std::stop_token token_;
150   
        std::stop_token token_;
150   
        mutable std::error_code ec_;
151   
        mutable std::error_code ec_;
151  
152  
152   
        connect_awaitable(tcp_socket& s, endpoint ep) noexcept
153   
        connect_awaitable(tcp_socket& s, endpoint ep) noexcept
153   
            : s_(s)
154   
            : s_(s)
154   
            , endpoint_(ep)
155   
            , endpoint_(ep)
155   
        {
156   
        {
156   
        }
157   
        }
157  
158  
158   
        bool await_ready() const noexcept
159   
        bool await_ready() const noexcept
159   
        {
160   
        {
160   
            return token_.stop_requested();
161   
            return token_.stop_requested();
161   
        }
162   
        }
162  
163  
163   
        capy::io_result<> await_resume() const noexcept
164   
        capy::io_result<> await_resume() const noexcept
164   
        {
165   
        {
165   
            if (token_.stop_requested())
166   
            if (token_.stop_requested())
166   
                return {make_error_code(std::errc::operation_canceled)};
167   
                return {make_error_code(std::errc::operation_canceled)};
167   
            return {ec_};
168   
            return {ec_};
168   
        }
169   
        }
169  
170  
170   
        auto await_suspend(std::coroutine_handle<> h, capy::io_env const* env)
171   
        auto await_suspend(std::coroutine_handle<> h, capy::io_env const* env)
171   
            -> std::coroutine_handle<>
172   
            -> std::coroutine_handle<>
172   
        {
173   
        {
173   
            token_ = env->stop_token;
174   
            token_ = env->stop_token;
174   
            return s_.get().connect(h, env->executor, endpoint_, token_, &ec_);
175   
            return s_.get().connect(h, env->executor, endpoint_, token_, &ec_);
175   
        }
176   
        }
176   
    };
177   
    };
177  
178  
178   
public:
179   
public:
179   
    /** Destructor.
180   
    /** Destructor.
180  
181  
181   
        Closes the socket if open, cancelling any pending operations.
182   
        Closes the socket if open, cancelling any pending operations.
182   
    */
183   
    */
183   
    ~tcp_socket() override;
184   
    ~tcp_socket() override;
184  
185  
185   
    /** Construct a socket from an execution context.
186   
    /** Construct a socket from an execution context.
186  
187  
187   
        @param ctx The execution context that will own this socket.
188   
        @param ctx The execution context that will own this socket.
188   
    */
189   
    */
189   
    explicit tcp_socket(capy::execution_context& ctx);
190   
    explicit tcp_socket(capy::execution_context& ctx);
190  
191  
191   
    /** Construct a socket from an executor.
192   
    /** Construct a socket from an executor.
192  
193  
193   
        The socket is associated with the executor's context.
194   
        The socket is associated with the executor's context.
194  
195  
195   
        @param ex The executor whose context will own the socket.
196   
        @param ex The executor whose context will own the socket.
196   
    */
197   
    */
197   
    template<class Ex>
198   
    template<class Ex>
198   
        requires(!std::same_as<std::remove_cvref_t<Ex>, tcp_socket>) &&
199   
        requires(!std::same_as<std::remove_cvref_t<Ex>, tcp_socket>) &&
199   
        capy::Executor<Ex>
200   
        capy::Executor<Ex>
200   
    explicit tcp_socket(Ex const& ex) : tcp_socket(ex.context())
201   
    explicit tcp_socket(Ex const& ex) : tcp_socket(ex.context())
201   
    {
202   
    {
202   
    }
203   
    }
203  
204  
204   
    /** Move constructor.
205   
    /** Move constructor.
205  
206  
206   
        Transfers ownership of the socket resources.
207   
        Transfers ownership of the socket resources.
207  
208  
208   
        @param other The socket to move from.
209   
        @param other The socket to move from.
209  
210  
210   
        @pre No awaitables returned by @p other's methods exist.
211   
        @pre No awaitables returned by @p other's methods exist.
211   
        @pre @p other is not referenced as a peer in any outstanding
212   
        @pre @p other is not referenced as a peer in any outstanding
212   
            accept awaitable.
213   
            accept awaitable.
213   
        @pre The execution context associated with @p other must
214   
        @pre The execution context associated with @p other must
214   
            outlive this socket.
215   
            outlive this socket.
215   
    */
216   
    */
216   
    tcp_socket(tcp_socket&& other) noexcept : io_object(std::move(other)) {}
217   
    tcp_socket(tcp_socket&& other) noexcept : io_object(std::move(other)) {}
217  
218  
218   
    /** Move assignment operator.
219   
    /** Move assignment operator.
219  
220  
220   
        Closes any existing socket and transfers ownership.
221   
        Closes any existing socket and transfers ownership.
221  
222  
222   
        @param other The socket to move from.
223   
        @param other The socket to move from.
223  
224  
224   
        @pre No awaitables returned by either `*this` or @p other's
225   
        @pre No awaitables returned by either `*this` or @p other's
225   
            methods exist.
226   
            methods exist.
226   
        @pre Neither `*this` nor @p other is referenced as a peer in
227   
        @pre Neither `*this` nor @p other is referenced as a peer in
227   
            any outstanding accept awaitable.
228   
            any outstanding accept awaitable.
228   
        @pre The execution context associated with @p other must
229   
        @pre The execution context associated with @p other must
229   
            outlive this socket.
230   
            outlive this socket.
230  
231  
231   
        @return Reference to this socket.
232   
        @return Reference to this socket.
232   
    */
233   
    */
233   
    tcp_socket& operator=(tcp_socket&& other) noexcept
234   
    tcp_socket& operator=(tcp_socket&& other) noexcept
234   
    {
235   
    {
235   
        if (this != &other)
236   
        if (this != &other)
236   
        {
237   
        {
237   
            close();
238   
            close();
238   
            h_ = std::move(other.h_);
239   
            h_ = std::move(other.h_);
239   
        }
240   
        }
240   
        return *this;
241   
        return *this;
241   
    }
242   
    }
242  
243  
243   
    tcp_socket(tcp_socket const&)            = delete;
244   
    tcp_socket(tcp_socket const&)            = delete;
244   
    tcp_socket& operator=(tcp_socket const&) = delete;
245   
    tcp_socket& operator=(tcp_socket const&) = delete;
245  
246  
246   
    /** Open the socket.
247   
    /** Open the socket.
247  
248  
248   
        Creates a TCP socket and associates it with the platform
249   
        Creates a TCP socket and associates it with the platform
249   
        reactor (IOCP on Windows). Calling @ref connect on a closed
250   
        reactor (IOCP on Windows). Calling @ref connect on a closed
250   
        socket opens it automatically with the endpoint's address family,
251   
        socket opens it automatically with the endpoint's address family,
251   
        so explicit `open()` is only needed when socket options must be
252   
        so explicit `open()` is only needed when socket options must be
252   
        set before connecting.
253   
        set before connecting.
253  
254  
254   
        @param proto The protocol (IPv4 or IPv6). Defaults to
255   
        @param proto The protocol (IPv4 or IPv6). Defaults to
255   
            `tcp::v4()`.
256   
            `tcp::v4()`.
256  
257  
257   
        @throws std::system_error on failure.
258   
        @throws std::system_error on failure.
258   
    */
259   
    */
259 - 
    void open( tcp proto = tcp::v4() );
260 + 
    void open(tcp proto = tcp::v4());
260  
261  
261   
    /** Close the socket.
262   
    /** Close the socket.
262  
263  
263   
        Releases socket resources. Any pending operations complete
264   
        Releases socket resources. Any pending operations complete
264   
        with `errc::operation_canceled`.
265   
        with `errc::operation_canceled`.
265   
    */
266   
    */
266   
    void close();
267   
    void close();
267  
268  
268   
    /** Check if the socket is open.
269   
    /** Check if the socket is open.
269  
270  
270   
        @return `true` if the socket is open and ready for operations.
271   
        @return `true` if the socket is open and ready for operations.
271   
    */
272   
    */
272   
    bool is_open() const noexcept
273   
    bool is_open() const noexcept
273   
    {
274   
    {
274   
#if BOOST_COROSIO_HAS_IOCP && !defined(BOOST_COROSIO_MRDOCS)
275   
#if BOOST_COROSIO_HAS_IOCP && !defined(BOOST_COROSIO_MRDOCS)
275   
        return h_ && get().native_handle() != ~native_handle_type(0);
276   
        return h_ && get().native_handle() != ~native_handle_type(0);
276   
#else
277   
#else
277   
        return h_ && get().native_handle() >= 0;
278   
        return h_ && get().native_handle() >= 0;
278   
#endif
279   
#endif
279   
    }
280   
    }
280  
281  
281   
    /** Initiate an asynchronous connect operation.
282   
    /** Initiate an asynchronous connect operation.
282  
283  
283   
        If the socket is not already open, it is opened automatically
284   
        If the socket is not already open, it is opened automatically
284   
        using the address family of @p ep (IPv4 or IPv6). If the socket
285   
        using the address family of @p ep (IPv4 or IPv6). If the socket
285   
        is already open, the existing file descriptor is used as-is.
286   
        is already open, the existing file descriptor is used as-is.
286  
287  
287   
        The operation supports cancellation via `std::stop_token` through
288   
        The operation supports cancellation via `std::stop_token` through
288   
        the affine awaitable protocol. If the associated stop token is
289   
        the affine awaitable protocol. If the associated stop token is
289   
        triggered, the operation completes immediately with
290   
        triggered, the operation completes immediately with
290   
        `errc::operation_canceled`.
291   
        `errc::operation_canceled`.
291  
292  
292   
        @param ep The remote endpoint to connect to.
293   
        @param ep The remote endpoint to connect to.
293  
294  
294   
        @return An awaitable that completes with `io_result<>`.
295   
        @return An awaitable that completes with `io_result<>`.
295   
            Returns success (default error_code) on successful connection,
296   
            Returns success (default error_code) on successful connection,
296   
            or an error code on failure including:
297   
            or an error code on failure including:
297   
            - connection_refused: No server listening at endpoint
298   
            - connection_refused: No server listening at endpoint
298   
            - timed_out: Connection attempt timed out
299   
            - timed_out: Connection attempt timed out
299   
            - network_unreachable: No route to host
300   
            - network_unreachable: No route to host
300   
            - operation_canceled: Cancelled via stop_token or cancel().
301   
            - operation_canceled: Cancelled via stop_token or cancel().
301   
                Check `ec == cond::canceled` for portable comparison.
302   
                Check `ec == cond::canceled` for portable comparison.
302  
303  
303   
        @throws std::system_error if the socket needs to be opened
304   
        @throws std::system_error if the socket needs to be opened
304   
            and the open fails.
305   
            and the open fails.
305  
306  
306   
        @par Preconditions
307   
        @par Preconditions
307   
        This socket must outlive the returned awaitable.
308   
        This socket must outlive the returned awaitable.
308  
309  
309   
        @par Example
310   
        @par Example
310   
        @code
311   
        @code
311   
        // Socket opened automatically with correct address family:
312   
        // Socket opened automatically with correct address family:
312   
        auto [ec] = co_await s.connect(endpoint);
313   
        auto [ec] = co_await s.connect(endpoint);
313   
        if (ec) { ... }
314   
        if (ec) { ... }
314   
        @endcode
315   
        @endcode
315   
    */
316   
    */
316   
    auto connect(endpoint ep)
317   
    auto connect(endpoint ep)
317   
    {
318   
    {
318   
        if (!is_open())
319   
        if (!is_open())
319   
            open(ep.is_v6() ? tcp::v6() : tcp::v4());
320   
            open(ep.is_v6() ? tcp::v6() : tcp::v4());
320   
        return connect_awaitable(*this, ep);
321   
        return connect_awaitable(*this, ep);
321   
    }
322   
    }
322  
323  
323   
    /** Cancel any pending asynchronous operations.
324   
    /** Cancel any pending asynchronous operations.
324  
325  
325   
        All outstanding operations complete with `errc::operation_canceled`.
326   
        All outstanding operations complete with `errc::operation_canceled`.
326   
        Check `ec == cond::canceled` for portable comparison.
327   
        Check `ec == cond::canceled` for portable comparison.
327   
    */
328   
    */
328   
    void cancel();
329   
    void cancel();
329  
330  
330   
    /** Get the native socket handle.
331   
    /** Get the native socket handle.
331  
332  
332   
        Returns the underlying platform-specific socket descriptor.
333   
        Returns the underlying platform-specific socket descriptor.
333   
        On POSIX systems this is an `int` file descriptor.
334   
        On POSIX systems this is an `int` file descriptor.
334   
        On Windows this is a `SOCKET` handle.
335   
        On Windows this is a `SOCKET` handle.
335  
336  
336   
        @return The native socket handle, or -1/INVALID_SOCKET if not open.
337   
        @return The native socket handle, or -1/INVALID_SOCKET if not open.
337  
338  
338   
        @par Preconditions
339   
        @par Preconditions
339   
        None. May be called on closed sockets.
340   
        None. May be called on closed sockets.
340   
    */
341   
    */
341   
    native_handle_type native_handle() const noexcept;
342   
    native_handle_type native_handle() const noexcept;
342  
343  
343   
    /** Disable sends or receives on the socket.
344   
    /** Disable sends or receives on the socket.
344  
345  
345   
        TCP connections are full-duplex: each direction (send and receive)
346   
        TCP connections are full-duplex: each direction (send and receive)
346   
        operates independently. This function allows you to close one or
347   
        operates independently. This function allows you to close one or
347   
        both directions without destroying the socket.
348   
        both directions without destroying the socket.
348  
349  
349   
        @li @ref shutdown_send sends a TCP FIN packet to the peer,
350   
        @li @ref shutdown_send sends a TCP FIN packet to the peer,
350   
            signaling that you have no more data to send. You can still
351   
            signaling that you have no more data to send. You can still
351   
            receive data until the peer also closes their send direction.
352   
            receive data until the peer also closes their send direction.
352   
            This is the most common use case, typically called before
353   
            This is the most common use case, typically called before
353   
            close() to ensure graceful connection termination.
354   
            close() to ensure graceful connection termination.
354  
355  
355   
        @li @ref shutdown_receive disables reading on the socket. This
356   
        @li @ref shutdown_receive disables reading on the socket. This
356   
            does NOT send anything to the peer - they are not informed
357   
            does NOT send anything to the peer - they are not informed
357   
            and may continue sending data. Subsequent reads will fail
358   
            and may continue sending data. Subsequent reads will fail
358   
            or return end-of-file. Incoming data may be discarded or
359   
            or return end-of-file. Incoming data may be discarded or
359   
            buffered depending on the operating system.
360   
            buffered depending on the operating system.
360  
361  
361   
        @li @ref shutdown_both combines both effects: sends a FIN and
362   
        @li @ref shutdown_both combines both effects: sends a FIN and
362   
            disables reading.
363   
            disables reading.
363  
364  
364   
        When the peer shuts down their send direction (sends a FIN),
365   
        When the peer shuts down their send direction (sends a FIN),
365   
        subsequent read operations will complete with `capy::cond::eof`.
366   
        subsequent read operations will complete with `capy::cond::eof`.
366   
        Use the portable condition test rather than comparing error
367   
        Use the portable condition test rather than comparing error
367   
        codes directly:
368   
        codes directly:
368  
369  
369   
        @code
370   
        @code
370   
        auto [ec, n] = co_await sock.read_some(buffer);
371   
        auto [ec, n] = co_await sock.read_some(buffer);
371   
        if (ec == capy::cond::eof)
372   
        if (ec == capy::cond::eof)
372   
        {
373   
        {
373   
            // Peer closed their send direction
374   
            // Peer closed their send direction
374   
        }
375   
        }
375   
        @endcode
376   
        @endcode
376  
377  
377   
        Any error from the underlying system call is silently discarded
378   
        Any error from the underlying system call is silently discarded
378   
        because it is unlikely to be helpful.
379   
        because it is unlikely to be helpful.
379  
380  
380   
        @param what Determines what operations will no longer be allowed.
381   
        @param what Determines what operations will no longer be allowed.
381   
    */
382   
    */
382   
    void shutdown(shutdown_type what);
383   
    void shutdown(shutdown_type what);
383  
384  
384   
    /** Set a socket option.
385   
    /** Set a socket option.
385  
386  
386   
        Applies a type-safe socket option to the underlying socket.
387   
        Applies a type-safe socket option to the underlying socket.
387   
        The option type encodes the protocol level and option name.
388   
        The option type encodes the protocol level and option name.
388  
389  
389   
        @par Example
390   
        @par Example
390   
        @code
391   
        @code
391   
        sock.set_option( socket_option::no_delay( true ) );
392   
        sock.set_option( socket_option::no_delay( true ) );
392   
        sock.set_option( socket_option::receive_buffer_size( 65536 ) );
393   
        sock.set_option( socket_option::receive_buffer_size( 65536 ) );
393   
        @endcode
394   
        @endcode
394  
395  
395   
        @param opt The option to set.
396   
        @param opt The option to set.
396  
397  
397   
        @throws std::logic_error if the socket is not open.
398   
        @throws std::logic_error if the socket is not open.
398   
        @throws std::system_error on failure.
399   
        @throws std::system_error on failure.
399   
    */
400   
    */
400   
    template<class Option>
401   
    template<class Option>
401 - 
    void set_option( Option const& opt )
402 + 
    void set_option(Option const& opt)
402   
    {
403   
    {
403   
        if (!is_open())
404   
        if (!is_open())
404 - 
            detail::throw_logic_error( "set_option: socket not open" );
405 + 
            detail::throw_logic_error("set_option: socket not open");
405   
        std::error_code ec = get().set_option(
406   
        std::error_code ec = get().set_option(
406 - 
            Option::level(), Option::name(), opt.data(), opt.size() );
407 + 
            Option::level(), Option::name(), opt.data(), opt.size());
407   
        if (ec)
408   
        if (ec)
408 - 
            detail::throw_system_error( ec, "tcp_socket::set_option" );
409 + 
            detail::throw_system_error(ec, "tcp_socket::set_option");
409   
    }
410   
    }
410  
411  
411   
    /** Get a socket option.
412   
    /** Get a socket option.
412  
413  
413   
        Retrieves the current value of a type-safe socket option.
414   
        Retrieves the current value of a type-safe socket option.
414  
415  
415   
        @par Example
416   
        @par Example
416   
        @code
417   
        @code
417   
        auto nd = sock.get_option<socket_option::no_delay>();
418   
        auto nd = sock.get_option<socket_option::no_delay>();
418   
        if ( nd.value() )
419   
        if ( nd.value() )
419   
            // Nagle's algorithm is disabled
420   
            // Nagle's algorithm is disabled
420   
        @endcode
421   
        @endcode
421  
422  
422   
        @return The current option value.
423   
        @return The current option value.
423  
424  
424   
        @throws std::logic_error if the socket is not open.
425   
        @throws std::logic_error if the socket is not open.
425   
        @throws std::system_error on failure.
426   
        @throws std::system_error on failure.
426   
    */
427   
    */
427   
    template<class Option>
428   
    template<class Option>
428   
    Option get_option() const
429   
    Option get_option() const
429   
    {
430   
    {
430   
        if (!is_open())
431   
        if (!is_open())
431 - 
            detail::throw_logic_error( "get_option: socket not open" );
432 + 
            detail::throw_logic_error("get_option: socket not open");
432   
        Option opt{};
433   
        Option opt{};
433   
        std::size_t sz = opt.size();
434   
        std::size_t sz = opt.size();
434 - 
        std::error_code ec = get().get_option(
435 + 
        std::error_code ec =
435 - 
            Option::level(), Option::name(), opt.data(), &sz );
436 + 
            get().get_option(Option::level(), Option::name(), opt.data(), &sz);
436   
        if (ec)
437   
        if (ec)
437 - 
            detail::throw_system_error( ec, "tcp_socket::get_option" );
438 + 
            detail::throw_system_error(ec, "tcp_socket::get_option");
438 - 
        opt.resize( sz );
439 + 
        opt.resize(sz);
439   
        return opt;
440   
        return opt;
440   
    }
441   
    }
441  
442  
442   
    /** Get the local endpoint of the socket.
443   
    /** Get the local endpoint of the socket.
443  
444  
444   
        Returns the local address and port to which the socket is bound.
445   
        Returns the local address and port to which the socket is bound.
445   
        For a connected socket, this is the local side of the connection.
446   
        For a connected socket, this is the local side of the connection.
446   
        The endpoint is cached when the connection is established.
447   
        The endpoint is cached when the connection is established.
447  
448  
448   
        @return The local endpoint, or a default endpoint (0.0.0.0:0) if
449   
        @return The local endpoint, or a default endpoint (0.0.0.0:0) if
449   
            the socket is not connected.
450   
            the socket is not connected.
450  
451  
451   
        @par Thread Safety
452   
        @par Thread Safety
452   
        The cached endpoint value is set during connect/accept completion
453   
        The cached endpoint value is set during connect/accept completion
453   
        and cleared during close(). This function may be called concurrently
454   
        and cleared during close(). This function may be called concurrently
454   
        with I/O operations, but must not be called concurrently with
455   
        with I/O operations, but must not be called concurrently with
455   
        connect(), accept(), or close().
456   
        connect(), accept(), or close().
456   
    */
457   
    */
457   
    endpoint local_endpoint() const noexcept;
458   
    endpoint local_endpoint() const noexcept;
458  
459  
459   
    /** Get the remote endpoint of the socket.
460   
    /** Get the remote endpoint of the socket.
460  
461  
461   
        Returns the remote address and port to which the socket is connected.
462   
        Returns the remote address and port to which the socket is connected.
462   
        The endpoint is cached when the connection is established.
463   
        The endpoint is cached when the connection is established.
463  
464  
464   
        @return The remote endpoint, or a default endpoint (0.0.0.0:0) if
465   
        @return The remote endpoint, or a default endpoint (0.0.0.0:0) if
465   
            the socket is not connected.
466   
            the socket is not connected.
466  
467  
467   
        @par Thread Safety
468   
        @par Thread Safety
468   
        The cached endpoint value is set during connect/accept completion
469   
        The cached endpoint value is set during connect/accept completion
469   
        and cleared during close(). This function may be called concurrently
470   
        and cleared during close(). This function may be called concurrently
470   
        with I/O operations, but must not be called concurrently with
471   
        with I/O operations, but must not be called concurrently with
471   
        connect(), accept(), or close().
472   
        connect(), accept(), or close().
472   
    */
473   
    */
473   
    endpoint remote_endpoint() const noexcept;
474   
    endpoint remote_endpoint() const noexcept;
474  
475  
475   
protected:
476   
protected:
476   
    tcp_socket() noexcept = default;
477   
    tcp_socket() noexcept = default;
477  
478  
478   
    explicit tcp_socket(handle h) noexcept : io_object(std::move(h)) {}
479   
    explicit tcp_socket(handle h) noexcept : io_object(std::move(h)) {}
479  
480  
480   
private:
481   
private:
481   
    friend class tcp_acceptor;
482   
    friend class tcp_acceptor;
482  
483  
483   
    /// Open the socket for the given protocol triple.
484   
    /// Open the socket for the given protocol triple.
484   
    void open_for_family(int family, int type, int protocol);
485   
    void open_for_family(int family, int type, int protocol);
485  
486  
486   
    inline implementation& get() const noexcept
487   
    inline implementation& get() const noexcept
487   
    {
488   
    {
488   
        return *static_cast<implementation*>(h_.get());
489   
        return *static_cast<implementation*>(h_.get());
489   
    }
490   
    }
490   
};
491   
};
491  
492  
492   
} // namespace boost::corosio
493   
} // namespace boost::corosio
493  
494  
494   
#endif
495   
#endif