include/boost/corosio/tcp_acceptor.hpp

91.7% Lines (44/48) 100.0% List of functions (16/16) 60.7% Branches (17/28)

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

f(x) Functions (16)

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_ACCEPTOR_HPP
12			#define BOOST_COROSIO_TCP_ACCEPTOR_HPP
13
14			#include <boost/corosio/detail/config.hpp>
15			#include <boost/corosio/detail/except.hpp>
16			#include <boost/corosio/io/io_object.hpp>
17			#include <boost/capy/io_result.hpp>
18			#include <boost/corosio/endpoint.hpp>
19			#include <boost/corosio/tcp.hpp>
20			#include <boost/corosio/tcp_socket.hpp>
21			#include <boost/capy/ex/executor_ref.hpp>
22			#include <boost/capy/ex/execution_context.hpp>
23			#include <boost/capy/ex/io_env.hpp>
24			#include <boost/capy/concept/executor.hpp>
25
26			#include <system_error>
27
28			#include <concepts>
29			#include <coroutine>
30			#include <cstddef>
31			#include <stop_token>
32			#include <type_traits>
33
34			namespace boost::corosio {
35
36			/** An asynchronous TCP acceptor for coroutine I/O.
37
38			This class provides asynchronous TCP accept operations that return
39			awaitable types. The acceptor binds to a local endpoint and listens
40			for incoming connections.
41
42			Each accept operation participates in the affine awaitable protocol,
43			ensuring coroutines resume on the correct executor.
44
45			@par Thread Safety
46			Distinct objects: Safe.@n
47			Shared objects: Unsafe. An acceptor must not have concurrent accept
48			operations.
49
50			@par Semantics
51			Wraps the platform TCP listener. Operations dispatch to
52			OS accept APIs via the io_context reactor.
53
54			@par Example
55			@code
56			// Convenience constructor: open + SO_REUSEADDR + bind + listen
57			io_context ioc;
58			tcp_acceptor acc( ioc, endpoint( 8080 ) );
59
60			tcp_socket peer( ioc );
61			auto [ec] = co_await acc.accept( peer );
62			if ( !ec ) {
63			// peer is now a connected socket
64			auto [ec2, n] = co_await peer.read_some( buf );
65			}
66			@endcode
67
68			@par Example
69			@code
70			// Fine-grained setup
71			tcp_acceptor acc( ioc );
72			acc.open( tcp::v6() );
73			acc.set_option( socket_option::reuse_address( true ) );
74			acc.set_option( socket_option::v6_only( true ) );
75			if ( auto ec = acc.bind( endpoint( ipv6_address::any(), 8080 ) ) )
76			return ec;
77			if ( auto ec = acc.listen() )
78			return ec;
79			@endcode
80			*/
81			class BOOST_COROSIO_DECL tcp_acceptor : public io_object
82			{
83			struct accept_awaitable
84			{
85			tcp_acceptor& acc_;
86			tcp_socket& peer_;
87			std::stop_token token_;
88			mutable std::error_code ec_;
89		7404x	mutable io_object::implementation* peer_impl_ = nullptr;
90
91		22212x	accept_awaitable(tcp_acceptor& acc, tcp_socket& peer) noexcept
92		7404x	: acc_(acc)
93		7404x	, peer_(peer)
94		7404x	{
95		14808x	}
96
97		7404x	bool await_ready() const noexcept
98			{
99		7404x	return token_.stop_requested();
100			}
101
102		7404x	capy::io_result<> await_resume() const noexcept
103			{
104	2/2 ✓ Branch 0 taken 6 times. ✓ Branch 1 taken 7398 times.	7404x	if (token_.stop_requested())
105		6x	return {make_error_code(std::errc::operation_canceled)};
106
107	3/4 ✓ Branch 0 taken 7392 times. ✓ Branch 1 taken 6 times. ✗ Branch 2 not taken. ✓ Branch 3 taken 7392 times.	7398x	if (!ec_ && peer_impl_)
108		7392x	peer_.h_.reset(peer_impl_);
109		7398x	return {ec_};
110		7404x	}
111
112		7404x	auto await_suspend(std::coroutine_handle<> h, capy::io_env const* env)
113			-> std::coroutine_handle<>
114			{
115		7404x	token_ = env->stop_token;
116	2/4 ✓ Branch 0 taken 7404 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 7404 times. ✗ Branch 3 not taken.	14808x	return acc_.get().accept(
117		7404x	h, env->executor, token_, &ec_, &peer_impl_);
118		✗	}
119			};
120
121			public:
122			/** Destructor.
123
124			Closes the acceptor if open, cancelling any pending operations.
125			*/
126			~tcp_acceptor() override;
127
128			/** Construct an acceptor from an execution context.
129
130			@param ctx The execution context that will own this acceptor.
131			*/
132			explicit tcp_acceptor(capy::execution_context& ctx);
133
134			/** Convenience constructor: open + SO_REUSEADDR + bind + listen.
135
136			Creates a fully-bound listening acceptor in a single
137			expression. The address family is deduced from @p ep.
138
139			@param ctx The execution context that will own this acceptor.
140			@param ep The local endpoint to bind to.
141			@param backlog The maximum pending connection queue length.
142
143			@throws std::system_error on bind or listen failure.
144			*/
145			tcp_acceptor(capy::execution_context& ctx, endpoint ep, int backlog = 128);
146
147			/** Construct an acceptor from an executor.
148
149			The acceptor is associated with the executor's context.
150
151			@param ex The executor whose context will own the acceptor.
152			*/
153			template<class Ex>
154			requires(!std::same_as<std::remove_cvref_t<Ex>, tcp_acceptor>) &&
155			capy::Executor<Ex>
156			explicit tcp_acceptor(Ex const& ex) : tcp_acceptor(ex.context())
157			{
158			}
159
160			/** Convenience constructor from an executor.
161
162			@param ex The executor whose context will own the acceptor.
163			@param ep The local endpoint to bind to.
164			@param backlog The maximum pending connection queue length.
165
166			@throws std::system_error on bind or listen failure.
167			*/
168			template<class Ex>
169			requires capy::Executor<Ex>
170			tcp_acceptor(Ex const& ex, endpoint ep, int backlog = 128)
171			: tcp_acceptor(ex.context(), ep, backlog)
172			{
173			}
174
175			/** Move constructor.
176
177			Transfers ownership of the acceptor resources.
178
179			@param other The acceptor to move from.
180
181			@pre No awaitables returned by @p other's methods exist.
182			@pre The execution context associated with @p other must
183			outlive this acceptor.
184			*/
185		6x	tcp_acceptor(tcp_acceptor&& other) noexcept : io_object(std::move(other)) {}
186
187			/** Move assignment operator.
188
189			Closes any existing acceptor and transfers ownership.
190
191			@param other The acceptor to move from.
192
193			@pre No awaitables returned by either `*this` or @p other's
194			methods exist.
195			@pre The execution context associated with @p other must
196			outlive this acceptor.
197
198			@return Reference to this acceptor.
199			*/
200		2x	tcp_acceptor& operator=(tcp_acceptor&& other) noexcept
201			{
202	1/2 ✗ Branch 0 not taken. ✓ Branch 1 taken 2 times.	2x	if (this != &other)
203			{
204	1/2 ✓ Branch 0 taken 2 times. ✗ Branch 1 not taken.	2x	close();
205		2x	h_ = std::move(other.h_);
206		2x	}
207		2x	return *this;
208			}
209
210			tcp_acceptor(tcp_acceptor const&) = delete;
211			tcp_acceptor& operator=(tcp_acceptor const&) = delete;
212
213			/** Create the acceptor socket without binding or listening.
214
215			Creates a TCP socket with dual-stack enabled for IPv6.
216			Does not set SO_REUSEADDR — call `set_option` explicitly
217			if needed.
218
219			If the acceptor is already open, this function is a no-op.
220
221			@param proto The protocol (IPv4 or IPv6). Defaults to
222			`tcp::v4()`.
223
224			@throws std::system_error on failure.
225
226			@par Example
227			@code
228			acc.open( tcp::v6() );
229			acc.set_option( socket_option::reuse_address( true ) );
230			acc.bind( endpoint( ipv6_address::any(), 8080 ) );
231			acc.listen();
232			@endcode
233
234			@see bind, listen
235			*/
236			void open(tcp proto = tcp::v4());
237
238			/** Bind to a local endpoint.
239
240			The acceptor must be open. Binds the socket to @p ep and
241			caches the resolved local endpoint (useful when port 0 is
242			used to request an ephemeral port).
243
244			@param ep The local endpoint to bind to.
245
246			@return An error code indicating success or the reason for
247			failure.
248
249			@par Error Conditions
250			@li `errc::address_in_use`: The endpoint is already in use.
251			@li `errc::address_not_available`: The address is not available
252			on any local interface.
253			@li `errc::permission_denied`: Insufficient privileges to bind
254			to the endpoint (e.g., privileged port).
255
256			@throws std::logic_error if the acceptor is not open.
257			*/
258			[[nodiscard]] std::error_code bind(endpoint ep);
259
260			/** Start listening for incoming connections.
261
262			The acceptor must be open and bound. Registers the acceptor
263			with the platform reactor.
264
265			@param backlog The maximum length of the queue of pending
266			connections. Defaults to 128.
267
268			@return An error code indicating success or the reason for
269			failure.
270
271			@throws std::logic_error if the acceptor is not open.
272			*/
273			[[nodiscard]] std::error_code listen(int backlog = 128);
274
275			/** Close the acceptor.
276
277			Releases acceptor resources. Any pending operations complete
278			with `errc::operation_canceled`.
279			*/
280			void close();
281
282			/** Check if the acceptor is listening.
283
284			@return `true` if the acceptor is open and listening.
285			*/
286		16075x	bool is_open() const noexcept
287			{
288	2/2 ✓ Branch 0 taken 10 times. ✓ Branch 1 taken 16065 times.	16075x	return h_ && get().is_open();
289			}
290
291			/** Initiate an asynchronous accept operation.
292
293			Accepts an incoming connection and initializes the provided
294			socket with the new connection. The acceptor must be listening
295			before calling this function.
296
297			The operation supports cancellation via `std::stop_token` through
298			the affine awaitable protocol. If the associated stop token is
299			triggered, the operation completes immediately with
300			`errc::operation_canceled`.
301
302			@param peer The socket to receive the accepted connection. Any
303			existing connection on this socket will be closed.
304
305			@return An awaitable that completes with `io_result<>`.
306			Returns success on successful accept, or an error code on
307			failure including:
308			- operation_canceled: Cancelled via stop_token or cancel().
309			Check `ec == cond::canceled` for portable comparison.
310
311			@par Preconditions
312			The acceptor must be listening (`is_open() == true`).
313			The peer socket must be associated with the same execution context.
314
315			Both this acceptor and @p peer must outlive the returned
316			awaitable.
317
318			@par Example
319			@code
320			tcp_socket peer(ioc);
321			auto [ec] = co_await acc.accept(peer);
322			if (!ec) {
323			// Use peer socket
324			}
325			@endcode
326			*/
327		7404x	auto accept(tcp_socket& peer)
328			{
329	1/2 ✓ Branch 0 taken 7404 times. ✗ Branch 1 not taken.	7404x	if (!is_open())
330		✗	detail::throw_logic_error("accept: acceptor not listening");
331		7404x	return accept_awaitable(*this, peer);
332			}
333
334			/** Cancel any pending asynchronous operations.
335
336			All outstanding operations complete with `errc::operation_canceled`.
337			Check `ec == cond::canceled` for portable comparison.
338			*/
339			void cancel();
340
341			/** Get the local endpoint of the acceptor.
342
343			Returns the local address and port to which the acceptor is bound.
344			This is useful when binding to port 0 (ephemeral port) to discover
345			the OS-assigned port number. The endpoint is cached when listen()
346			is called.
347
348			@return The local endpoint, or a default endpoint (0.0.0.0:0) if
349			the acceptor is not listening.
350
351			@par Thread Safety
352			The cached endpoint value is set during listen() and cleared
353			during close(). This function may be called concurrently with
354			accept operations, but must not be called concurrently with
355			listen() or close().
356			*/
357			endpoint local_endpoint() const noexcept;
358
359			/** Set a socket option on the acceptor.
360
361			Applies a type-safe socket option to the underlying listening
362			socket. The socket must be open (via `open()` or `listen()`).
363			This is useful for setting options between `open()` and
364			`listen()`, such as `socket_option::reuse_port`.
365
366			@par Example
367			@code
368			acc.open( tcp::v6() );
369			acc.set_option( socket_option::reuse_port( true ) );
370			acc.bind( endpoint( ipv6_address::any(), 8080 ) );
371			acc.listen();
372			@endcode
373
374			@param opt The option to set.
375
376			@throws std::logic_error if the acceptor is not open.
377			@throws std::system_error on failure.
378			*/
379			template<class Option>
380		1232x	void set_option(Option const& opt)
381			{
382	2/4 ✓ Branch 0 taken 1230 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken.	1232x	if (!is_open())
383		✗	detail::throw_logic_error("set_option: acceptor not open");
384		2464x	std::error_code ec = get().set_option(
385		1232x	Option::level(), Option::name(), opt.data(), opt.size());
386	2/4 ✓ Branch 0 taken 1230 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 2 times. ✗ Branch 3 not taken.	1232x	if (ec)
387		✗	detail::throw_system_error(ec, "tcp_acceptor::set_option");
388		1232x	}
389
390			/** Get a socket option from the acceptor.
391
392			Retrieves the current value of a type-safe socket option.
393
394			@par Example
395			@code
396			auto opt = acc.get_option<socket_option::reuse_address>();
397			@endcode
398
399			@return The current option value.
400
401			@throws std::logic_error if the acceptor is not open.
402			@throws std::system_error on failure.
403			*/
404			template<class Option>
405			Option get_option() const
406			{
407			if (!is_open())
408			detail::throw_logic_error("get_option: acceptor not open");
409			Option opt{};
410			std::size_t sz = opt.size();
411			std::error_code ec =
412			get().get_option(Option::level(), Option::name(), opt.data(), &sz);
413			if (ec)
414			detail::throw_system_error(ec, "tcp_acceptor::get_option");
415			opt.resize(sz);
416			return opt;
417			}
418
419			/** Define backend hooks for TCP acceptor operations.
420
421			Platform backends derive from this to implement
422			accept, endpoint query, open-state checks, cancellation,
423			and socket-option management.
424			*/
425			struct implementation : io_object::implementation
426			{
427			/// Initiate an asynchronous accept operation.
428			virtual std::coroutine_handle<> accept(
429			std::coroutine_handle<>,
430			capy::executor_ref,
431			std::stop_token,
432			std::error_code*,
433			io_object::implementation**) = 0;
434
435			/// Returns the cached local endpoint.
436			virtual endpoint local_endpoint() const noexcept = 0;
437
438			/// Return true if the acceptor has a kernel resource open.
439			virtual bool is_open() const noexcept = 0;
440
441			/** Cancel any pending asynchronous operations.
442
443			All outstanding operations complete with operation_canceled error.
444			*/
445			virtual void cancel() noexcept = 0;
446
447			/** Set a socket option.
448
449			@param level The protocol level.
450			@param optname The option name.
451			@param data Pointer to the option value.
452			@param size Size of the option value in bytes.
453			@return Error code on failure, empty on success.
454			*/
455			virtual std::error_code set_option(
456			int level,
457			int optname,
458			void const* data,
459			std::size_t size) noexcept = 0;
460
461			/** Get a socket option.
462
463			@param level The protocol level.
464			@param optname The option name.
465			@param data Pointer to receive the option value.
466			@param size On entry, the size of the buffer. On exit,
467			the size of the option value.
468			@return Error code on failure, empty on success.
469			*/
470			virtual std::error_code
471			get_option(int level, int optname, void* data, std::size_t* size)
472			const noexcept = 0;
473			};
474
475			protected:
476		16x	explicit tcp_acceptor(handle h) noexcept : io_object(std::move(h)) {}
477
478			/// Transfer accepted peer impl to the peer socket.
479			static void
480		10x	reset_peer_impl(tcp_socket& peer, io_object::implementation* impl) noexcept
481			{
482	1/2 ✗ Branch 0 not taken. ✓ Branch 1 taken 10 times.	10x	if (impl)
483		10x	peer.h_.reset(impl);
484		10x	}
485
486			private:
487		25924x	inline implementation& get() const noexcept
488			{
489		25924x	return static_cast<implementation>(h_.get());
490			}
491			};
492
493			} // namespace boost::corosio
494
495			#endif
496