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/detail/op_base.hpp>
19 : #include <boost/corosio/io/io_stream.hpp>
20 : #include <boost/capy/io_result.hpp>
21 : #include <boost/corosio/detail/buffer_param.hpp>
22 : #include <boost/corosio/endpoint.hpp>
23 : #include <boost/corosio/shutdown_type.hpp>
24 : #include <boost/corosio/tcp.hpp>
25 : #include <boost/corosio/wait_type.hpp>
26 : #include <boost/capy/ex/executor_ref.hpp>
27 : #include <boost/capy/ex/execution_context.hpp>
28 : #include <boost/capy/ex/io_env.hpp>
29 : #include <boost/capy/concept/executor.hpp>
30 :
31 : #include <system_error>
32 :
33 : #include <concepts>
34 : #include <coroutine>
35 : #include <cstddef>
36 : #include <stop_token>
37 : #include <type_traits>
38 :
39 : namespace boost::corosio {
40 :
41 : /** An asynchronous TCP socket for coroutine I/O.
42 :
43 : This class provides asynchronous TCP socket operations that return
44 : awaitable types. Each operation participates in the affine awaitable
45 : protocol, ensuring coroutines resume on the correct executor.
46 :
47 : The socket must be opened before performing I/O operations. Operations
48 : support cancellation through `std::stop_token` via the affine protocol,
49 : or explicitly through the `cancel()` member function.
50 :
51 : @par Thread Safety
52 : Distinct objects: Safe.@n
53 : Shared objects: Unsafe. A socket must not have concurrent operations
54 : of the same type (e.g., two simultaneous reads). One read and one
55 : write may be in flight simultaneously.
56 :
57 : @par Semantics
58 : Wraps the platform TCP/IP stack. Operations dispatch to
59 : OS socket APIs via the io_context reactor (epoll, IOCP,
60 : kqueue). Satisfies @ref capy::Stream.
61 :
62 : @par Example
63 : @code
64 : io_context ioc;
65 : tcp_socket s(ioc);
66 :
67 : // Using structured bindings
68 : auto [ec] = co_await s.connect(
69 : endpoint(ipv4_address::loopback(), 8080));
70 : if (ec)
71 : co_return;
72 :
73 : char buf[1024];
74 : auto [read_ec, n] = co_await s.read_some(
75 : capy::mutable_buffer(buf, sizeof(buf)));
76 : @endcode
77 : */
78 : class BOOST_COROSIO_DECL tcp_socket : public io_stream
79 : {
80 : public:
81 : /// The endpoint type used by this socket.
82 : using endpoint_type = corosio::endpoint;
83 :
84 : using shutdown_type = corosio::shutdown_type;
85 : using enum corosio::shutdown_type;
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 : /** Initiate an asynchronous wait for socket readiness.
112 :
113 : Completes when the socket becomes ready for the
114 : specified direction, or an error condition is
115 : reported. No bytes are transferred.
116 :
117 : @param h Coroutine handle to resume on completion.
118 : @param ex Executor for dispatching the completion.
119 : @param w The direction to wait on.
120 : @param token Stop token for cancellation.
121 : @param ec Output error code.
122 :
123 : @return Coroutine handle to resume immediately.
124 : */
125 : virtual std::coroutine_handle<> wait(
126 : std::coroutine_handle<> h,
127 : capy::executor_ref ex,
128 : wait_type w,
129 : std::stop_token token,
130 : std::error_code* ec) = 0;
131 :
132 : /** Shut down the socket for the given direction(s).
133 :
134 : @param what The shutdown direction.
135 :
136 : @return Error code on failure, empty on success.
137 : */
138 : virtual std::error_code shutdown(shutdown_type what) noexcept = 0;
139 :
140 : /// Return the platform socket descriptor.
141 : virtual native_handle_type native_handle() const noexcept = 0;
142 :
143 : /** Release ownership of the native socket handle.
144 :
145 : Deregisters the socket from the backend and cancels
146 : pending operations without closing the descriptor. The
147 : caller takes ownership.
148 :
149 : @return The native handle.
150 : */
151 : virtual native_handle_type release_socket() noexcept = 0;
152 :
153 : /** Request cancellation of pending asynchronous operations.
154 :
155 : All outstanding operations complete with operation_canceled error.
156 : Check `ec == cond::canceled` for portable comparison.
157 : */
158 : virtual void cancel() noexcept = 0;
159 :
160 : /** Set a socket option.
161 :
162 : @param level The protocol level (e.g. `SOL_SOCKET`).
163 : @param optname The option name (e.g. `SO_KEEPALIVE`).
164 : @param data Pointer to the option value.
165 : @param size Size of the option value in bytes.
166 : @return Error code on failure, empty on success.
167 : */
168 : virtual std::error_code set_option(
169 : int level,
170 : int optname,
171 : void const* data,
172 : std::size_t size) noexcept = 0;
173 :
174 : /** Get a socket option.
175 :
176 : @param level The protocol level (e.g. `SOL_SOCKET`).
177 : @param optname The option name (e.g. `SO_KEEPALIVE`).
178 : @param data Pointer to receive the option value.
179 : @param size On entry, the size of the buffer. On exit,
180 : the size of the option value.
181 : @return Error code on failure, empty on success.
182 : */
183 : virtual std::error_code
184 : get_option(int level, int optname, void* data, std::size_t* size)
185 : const noexcept = 0;
186 :
187 : /// Return the cached local endpoint.
188 : virtual endpoint local_endpoint() const noexcept = 0;
189 :
190 : /// Return the cached remote endpoint.
191 : virtual endpoint remote_endpoint() const noexcept = 0;
192 : };
193 :
194 : /// Represent the awaitable returned by @ref connect.
195 : struct connect_awaitable
196 : : detail::void_op_base<connect_awaitable>
197 : {
198 : tcp_socket& s_;
199 : endpoint endpoint_;
200 :
201 HIT 7006 : connect_awaitable(tcp_socket& s, endpoint ep) noexcept
202 7006 : : s_(s), endpoint_(ep) {}
203 :
204 7006 : std::coroutine_handle<> dispatch(
205 : std::coroutine_handle<> h, capy::executor_ref ex) const
206 : {
207 7006 : return s_.get().connect(h, ex, endpoint_, token_, &ec_);
208 : }
209 : };
210 :
211 : /// Represent the awaitable returned by @ref wait.
212 : struct wait_awaitable
213 : : detail::void_op_base<wait_awaitable>
214 : {
215 : tcp_socket& s_;
216 : wait_type w_;
217 :
218 37 : wait_awaitable(tcp_socket& s, wait_type w) noexcept
219 37 : : s_(s), w_(w) {}
220 :
221 37 : std::coroutine_handle<> dispatch(
222 : std::coroutine_handle<> h, capy::executor_ref ex) const
223 : {
224 37 : return s_.get().wait(h, ex, w_, token_, &ec_);
225 : }
226 : };
227 :
228 : public:
229 : /** Destructor.
230 :
231 : Closes the socket if open, cancelling any pending operations.
232 : */
233 : ~tcp_socket() override;
234 :
235 : /** Construct a socket from an execution context.
236 :
237 : @param ctx The execution context that will own this socket.
238 : */
239 : explicit tcp_socket(capy::execution_context& ctx);
240 :
241 : /** Construct a socket from an executor.
242 :
243 : The socket is associated with the executor's context.
244 :
245 : @param ex The executor whose context will own the socket.
246 : */
247 : template<class Ex>
248 : requires(!std::same_as<std::remove_cvref_t<Ex>, tcp_socket>) &&
249 : capy::Executor<Ex>
250 1 : explicit tcp_socket(Ex const& ex) : tcp_socket(ex.context())
251 : {
252 1 : }
253 :
254 : /** Move constructor.
255 :
256 : Transfers ownership of the socket resources.
257 :
258 : @param other The socket to move from.
259 :
260 : @pre No awaitables returned by @p other's methods exist.
261 : @pre @p other is not referenced as a peer in any outstanding
262 : accept awaitable.
263 : @pre The execution context associated with @p other must
264 : outlive this socket.
265 : */
266 471 : tcp_socket(tcp_socket&& other) noexcept : io_object(std::move(other)) {}
267 :
268 : /** Move assignment operator.
269 :
270 : Closes any existing socket and transfers ownership.
271 :
272 : @param other The socket to move from.
273 :
274 : @pre No awaitables returned by either `*this` or @p other's
275 : methods exist.
276 : @pre Neither `*this` nor @p other is referenced as a peer in
277 : any outstanding accept awaitable.
278 : @pre The execution context associated with @p other must
279 : outlive this socket.
280 :
281 : @return Reference to this socket.
282 : */
283 23 : tcp_socket& operator=(tcp_socket&& other) noexcept
284 : {
285 23 : if (this != &other)
286 : {
287 23 : close();
288 23 : h_ = std::move(other.h_);
289 : }
290 23 : return *this;
291 : }
292 :
293 : tcp_socket(tcp_socket const&) = delete;
294 : tcp_socket& operator=(tcp_socket const&) = delete;
295 :
296 : /** Open the socket.
297 :
298 : Creates a TCP socket and associates it with the platform
299 : reactor (IOCP on Windows). Calling @ref connect on a closed
300 : socket opens it automatically with the endpoint's address family,
301 : so explicit `open()` is only needed when socket options must be
302 : set before connecting.
303 :
304 : Failures such as descriptor exhaustion are normal runtime
305 : conditions and are reported through the returned error code.
306 : Opening an already-open socket is a no-op that reports
307 : success.
308 :
309 : @param proto The protocol (IPv4 or IPv6). Defaults to
310 : `tcp::v4()`.
311 :
312 : @return The error code, empty on success.
313 : */
314 : [[nodiscard]] std::error_code open(tcp proto = tcp::v4()) noexcept;
315 :
316 : /** Bind the socket to a local endpoint.
317 :
318 : Associates the socket with a local address and port before
319 : connecting. Useful for multi-homed hosts or source-port
320 : pinning.
321 :
322 : @param ep The local endpoint to bind to.
323 :
324 : @return An error code indicating success or the reason for
325 : failure.
326 :
327 : @par Error Conditions
328 : @li `errc::address_in_use`: The endpoint is already in use.
329 : @li `errc::address_not_available`: The address is not
330 : available on any local interface.
331 : @li `errc::permission_denied`: Insufficient privileges to
332 : bind to the endpoint (e.g., privileged port).
333 :
334 : A closed socket reports `errc::bad_file_descriptor`.
335 : */
336 : [[nodiscard]] std::error_code bind(endpoint ep) noexcept;
337 :
338 : /** Close the socket.
339 :
340 : Releases socket resources. Any pending operations complete
341 : with `errc::operation_canceled`.
342 : */
343 : void close() noexcept;
344 :
345 : /** Check if the socket is open.
346 :
347 : @return `true` if the socket is open and ready for operations.
348 : */
349 43528 : bool is_open() const noexcept
350 : {
351 : #if BOOST_COROSIO_HAS_IOCP && !defined(BOOST_COROSIO_MRDOCS)
352 : return h_ && get().native_handle() != ~native_handle_type(0);
353 : #else
354 43528 : return h_ && get().native_handle() >= 0;
355 : #endif
356 : }
357 :
358 : /** Initiate an asynchronous connect operation.
359 :
360 : If the socket is not already open, it is opened automatically
361 : using the address family of @p ep (IPv4 or IPv6). If the socket
362 : is already open, the existing file descriptor is used as-is.
363 :
364 : The operation supports cancellation via `std::stop_token` through
365 : the affine awaitable protocol. If the associated stop token is
366 : triggered, the operation completes immediately with
367 : `errc::operation_canceled`.
368 :
369 : @param ep The remote endpoint to connect to.
370 :
371 : @return An awaitable that completes with `io_result<>`.
372 : Returns success (default error_code) on successful connection,
373 : or an error code on failure including:
374 : - connection_refused: No server listening at endpoint
375 : - timed_out: Connection attempt timed out
376 : - network_unreachable: No route to host
377 : - operation_canceled: Cancelled via stop_token or cancel().
378 : Check `ec == cond::canceled` for portable comparison.
379 :
380 : If the socket needs to be opened and the open fails, the
381 : awaitable completes immediately with that error.
382 :
383 : @par Preconditions
384 : This socket must outlive the returned awaitable.
385 :
386 : @par Example
387 : @code
388 : // Socket opened automatically with correct address family:
389 : auto [ec] = co_await s.connect(endpoint);
390 : if (ec)
391 : co_return;
392 : @endcode
393 : */
394 7006 : [[nodiscard]] auto connect(endpoint ep)
395 : {
396 7006 : connect_awaitable aw(*this, ep);
397 7006 : if (!is_open())
398 62 : aw.ec_ = open(ep.is_v6() ? tcp::v6() : tcp::v4());
399 7006 : return aw;
400 : }
401 :
402 : /** Wait for the socket to become ready in a given direction.
403 :
404 : Suspends until the socket is ready for the requested
405 : direction, or an error condition is reported. No bytes
406 : are transferred — useful for integrating with C libraries
407 : that own the I/O on a nonblocking fd and only need
408 : readiness notification (e.g. libpq async, libssh).
409 :
410 : The operation supports cancellation via `std::stop_token`
411 : through the affine awaitable protocol. If the associated
412 : stop token is triggered, the operation completes
413 : immediately with `errc::operation_canceled`.
414 :
415 : @param w The wait direction (read, write, or error).
416 :
417 : @return An awaitable that completes with `io_result<>`.
418 : On success, no bytes have been consumed from the
419 : stream; a subsequent `read_some` (for read waits)
420 : returns the available data.
421 :
422 : A closed socket completes with `errc::bad_file_descriptor`.
423 :
424 : @par Preconditions
425 : This socket must outlive the returned awaitable.
426 : */
427 37 : [[nodiscard]] auto wait(wait_type w)
428 : {
429 37 : return wait_awaitable(*this, w);
430 : }
431 :
432 : /** Cancel any pending asynchronous operations.
433 :
434 : All outstanding operations complete with `errc::operation_canceled`.
435 : Check `ec == cond::canceled` for portable comparison.
436 : */
437 : void cancel() noexcept;
438 :
439 : /** Get the native socket handle.
440 :
441 : Returns the underlying platform-specific socket descriptor.
442 : On POSIX systems this is an `int` file descriptor.
443 : On Windows this is a `SOCKET` handle.
444 :
445 : @return The native socket handle, or -1/INVALID_SOCKET if not open.
446 :
447 : @par Preconditions
448 : None. May be called on closed sockets.
449 : */
450 : native_handle_type native_handle() const noexcept;
451 :
452 : /** Assign an existing native socket to this object.
453 :
454 : Adopts a TCP socket created outside the library — received
455 : from another process, inherited, or made natively — and
456 : registers it with the backend. The socket must be a stream
457 : socket in the `AF_INET` or `AF_INET6` family. Adoption never
458 : alters the descriptor's flags or options: on POSIX the fd
459 : must already be non-blocking, and on Windows the socket must
460 : be overlapped-capable.
461 :
462 : If this object is already open, pending operations complete
463 : with `errc::operation_canceled` and the held socket is
464 : closed before the new one is adopted.
465 :
466 : @par Exception Safety
467 : Strong guarantee on validation failure: the object is
468 : unchanged. If backend registration fails, the object either
469 : retains its previous socket or is left closed, depending on
470 : the backend. In all failure cases the caller retains
471 : ownership of `fd`.
472 :
473 : @param fd The native socket to adopt. On success the object
474 : owns it and will close it.
475 :
476 : @return The error code, empty on success. Validation and
477 : registration failures are normal runtime conditions when
478 : adopting foreign descriptors.
479 : */
480 : [[nodiscard]] std::error_code assign(native_handle_type fd) noexcept;
481 :
482 : /** Release ownership of the native socket handle.
483 :
484 : Deregisters the socket from the backend and cancels pending
485 : operations without closing the descriptor. The caller takes
486 : ownership of the returned handle.
487 :
488 : @return The native handle.
489 :
490 : @throws std::system_error `errc::bad_file_descriptor` if the
491 : socket is not open.
492 :
493 : @post is_open() == false
494 : */
495 : native_handle_type release();
496 :
497 : /** Disable sends or receives on the socket.
498 :
499 : TCP connections are full-duplex: each direction (send and receive)
500 : operates independently. This function allows you to close one or
501 : both directions without destroying the socket.
502 :
503 : @li @ref shutdown_send sends a TCP FIN packet to the peer,
504 : signaling that you have no more data to send. You can still
505 : receive data until the peer also closes their send direction.
506 : This is the most common use case, typically called before
507 : close() to ensure graceful connection termination.
508 :
509 : @li @ref shutdown_receive disables reading on the socket. This
510 : does NOT send anything to the peer - they are not informed
511 : and may continue sending data. Subsequent reads will fail
512 : or return end-of-file. Incoming data may be discarded or
513 : buffered depending on the operating system.
514 :
515 : @li @ref shutdown_both combines both effects: sends a FIN and
516 : disables reading.
517 :
518 : When the peer shuts down their send direction (sends a FIN),
519 : subsequent read operations will complete with `capy::cond::eof`.
520 : Use the portable condition test rather than comparing error
521 : codes directly:
522 :
523 : @code
524 : auto [ec, n] = co_await sock.read_some(buffer);
525 : if (ec == capy::cond::eof)
526 : co_return; // Peer closed their send direction
527 : @endcode
528 :
529 : Failures such as a peer that already disconnected are
530 : normal runtime conditions and are reported through the
531 : returned error code. A closed socket reports
532 : `errc::bad_file_descriptor`.
533 :
534 : @param what Determines what operations will no longer be allowed.
535 :
536 : @return The error code, empty on success.
537 : */
538 : [[nodiscard]] std::error_code shutdown(shutdown_type what) noexcept;
539 :
540 : /** Set a socket option.
541 :
542 : Applies a type-safe socket option to the underlying socket.
543 : The option type encodes the protocol level and option name.
544 :
545 : @par Example
546 : @code
547 : sock.set_option( socket_option::no_delay( true ) );
548 : sock.set_option( socket_option::receive_buffer_size( 65536 ) );
549 : @endcode
550 :
551 : @param opt The option to set.
552 :
553 : @throws std::system_error `errc::bad_file_descriptor` if the
554 : socket is not open; otherwise thrown on failure.
555 : */
556 : template<class Option>
557 219 : void set_option(Option const& opt)
558 : {
559 219 : if (!is_open())
560 2 : detail::throw_system_error(
561 4 : make_error_code(std::errc::bad_file_descriptor),
562 : "tcp_socket::set_option");
563 217 : std::error_code ec = get().set_option(
564 : Option::level(), Option::name(), opt.data(), opt.size());
565 217 : if (ec)
566 2 : detail::throw_system_error(ec, "tcp_socket::set_option");
567 215 : }
568 :
569 : /** Get a socket option.
570 :
571 : Retrieves the current value of a type-safe socket option.
572 :
573 : @par Example
574 : @code
575 : auto nd = sock.get_option<socket_option::no_delay>();
576 : bool disabled = nd.value(); // true: Nagle's algorithm is off
577 : @endcode
578 :
579 : @return The current option value.
580 :
581 : @throws std::system_error `errc::bad_file_descriptor` if the
582 : socket is not open; otherwise thrown on failure.
583 : */
584 : template<class Option>
585 85 : Option get_option() const
586 : {
587 85 : if (!is_open())
588 2 : detail::throw_system_error(
589 4 : make_error_code(std::errc::bad_file_descriptor),
590 : "tcp_socket::get_option");
591 83 : Option opt{};
592 83 : std::size_t sz = opt.size();
593 : std::error_code ec =
594 83 : get().get_option(Option::level(), Option::name(), opt.data(), &sz);
595 83 : if (ec)
596 2 : detail::throw_system_error(ec, "tcp_socket::get_option");
597 81 : opt.resize(sz);
598 81 : return opt;
599 : }
600 :
601 : /** Get the local endpoint of the socket.
602 :
603 : Returns the local address and port to which the socket is bound.
604 : For a connected socket, this is the local side of the connection.
605 : The endpoint is cached when the connection is established.
606 :
607 : @return The local endpoint, or a default endpoint (0.0.0.0:0) if
608 : the socket is not connected.
609 :
610 : @par Thread Safety
611 : The cached endpoint value is set during connect/accept completion
612 : and cleared during close(). This function may be called concurrently
613 : with I/O operations, but must not be called concurrently with
614 : connect(), accept(), or close().
615 : */
616 : endpoint local_endpoint() const noexcept;
617 :
618 : /** Get the remote endpoint of the socket.
619 :
620 : Returns the remote address and port to which the socket is connected.
621 : The endpoint is cached when the connection is established.
622 :
623 : @return The remote endpoint, or a default endpoint (0.0.0.0:0) if
624 : the socket is not connected.
625 :
626 : @par Thread Safety
627 : The cached endpoint value is set during connect/accept completion
628 : and cleared during close(). This function may be called concurrently
629 : with I/O operations, but must not be called concurrently with
630 : connect(), accept(), or close().
631 : */
632 : endpoint remote_endpoint() const noexcept;
633 :
634 : protected:
635 39 : tcp_socket() noexcept = default;
636 :
637 : explicit tcp_socket(handle h) noexcept : io_object(std::move(h)) {}
638 :
639 : private:
640 : friend class tcp_acceptor;
641 :
642 : /// Open the socket for the given protocol triple.
643 : [[nodiscard]] std::error_code
644 : open_for_family(int family, int type, int protocol) noexcept;
645 :
646 50732 : inline implementation& get() const noexcept
647 : {
648 50732 : return *static_cast<implementation*>(h_.get());
649 : }
650 : };
651 :
652 : } // namespace boost::corosio
653 :
654 : #endif
|
