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