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