include/boost/corosio/tcp_socket.hpp

87.0% Lines (40/46) 100.0% List of functions (31/31) 45.2% Branches (28/62)

[ ] prev/next file n p prev/next uncovered line

tcp_socket.hpp

f(x) Functions (31)

Function Calls Lines Branches Blocks

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