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