include/boost/corosio/tcp_acceptor.hpp

97.1% Lines (101 / 104) 70.0% Branches (42 / 60) 100.0% Functions (38 / 38)

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

tcp_acceptor.hpp

f(x) Functions (38)

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			// 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_ACCEPTOR_HPP
13			#define BOOST_COROSIO_TCP_ACCEPTOR_HPP
14
15			#include <boost/corosio/family.hpp>
16			#include <boost/corosio/detail/config.hpp>
17			#include <boost/corosio/detail/native_handle.hpp>
18			#include <boost/corosio/detail/op_base.hpp>
19			#include <boost/corosio/error.hpp>
20			#include <boost/corosio/wait_type.hpp>
21			#include <boost/corosio/io/io_object.hpp>
22			#include <boost/capy/results.hpp>
23			#include <boost/corosio/endpoint.hpp>
24			#include <boost/corosio/tcp_socket.hpp>
25			#include <boost/capy/ex/executor_ref.hpp>
26			#include <boost/capy/ex/execution_context.hpp>
27			#include <boost/capy/ex/await_context.hpp>
28			#include <boost/capy/concept/executor.hpp>
29
30			#include <system_error>
31
32			#include <concepts>
33			#include <boost/capy/continuation.hpp>
34
35			#include <coroutine>
36			#include <cstddef>
37			#include <stop_token>
38			#include <type_traits>
39			#include <utility>
40
41			namespace boost::corosio {
42
43			/** Accepts inbound TCP connections, from a coroutine.
44
45			This class provides asynchronous TCP accept operations that return
46			awaitable types. The acceptor binds to a local endpoint and listens
47			for incoming connections.
48
49			Each accept operation participates in the affine awaitable protocol,
50			ensuring coroutines resume on the correct executor.
51
52			@par Thread Safety
53			Distinct objects: Safe.@n
54			Shared objects: Unsafe. An acceptor must not have concurrent accept
55			operations.
56
57			@par Semantics
58			Wraps the platform TCP listener. Operations dispatch to
59			OS accept APIs via the `io_context` reactor.
60
61			@par Example
62			@par !example convenience_construction
63
64			@par Example
65			@par !example fine_grained_setup
66			*/
67			class BOOST_COROSIO_DECL tcp_acceptor : public io_object
68			{
69			struct wait_awaitable : detail::void_op_base<wait_awaitable>
70			{
71			private:
72			friend tcp_acceptor;
73
74		62x	wait_awaitable(tcp_acceptor& acc, wait_type w) noexcept
75		31x	: acc_(acc)
76		31x	, w_(w)
77		31x	{
78		62x	}
79
80			friend detail::void_op_base<wait_awaitable>;
81
82			tcp_acceptor& acc_;
83			wait_type w_;
84
85			std::coroutine_handle<>
86		27x	dispatch(capy::continuation& cont, capy::executor_ref ex) const
87			{
88	1/2 ✓ Branch 0 taken 27 times. ✗ Branch 1 not taken.	27x	return acc_.get().wait(cont, ex, w_, token_, &ec_);
89		✗	}
90			};
91
92			struct accept_awaitable : detail::void_op_base<accept_awaitable>
93			{
94			private:
95			friend tcp_acceptor;
96			friend detail::void_op_base<accept_awaitable>;
97
98			tcp_acceptor& acc_;
99			tcp_socket& peer_;
100		15257x	mutable io_object::implementation* peer_impl_ = nullptr;
101
102
103		30514x	accept_awaitable(tcp_acceptor& acc, tcp_socket& peer) noexcept
104		15257x	: acc_(acc)
105		15257x	, peer_(peer)
106		15257x	{
107		30514x	}
108
109			std::coroutine_handle<>
110		15249x	dispatch(capy::continuation& cont, capy::executor_ref ex) const
111			{
112	2/4 ✓ Branch 0 taken 15249 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 15249 times. ✗ Branch 3 not taken.	30498x	return acc_.get().accept(
113		15249x	cont, ex, this->token_, &this->ec_, &peer_impl_);
114		✗	}
115
116			public:
117			// A peer accepted for an awaiter that never resumed is closed
118			// here, or nothing would own it.
119		61028x	~accept_awaitable()
120		30514x	{
121	2/2 ✓ Branch 0 taken 30512 times. ✓ Branch 1 taken 2 times.	30514x	if (peer_impl_)
122		2x	discard_peer(acc_, peer_impl_);
123		61028x	}
124
125		14445x	[[nodiscard]] capy::results<> await_resume() const noexcept
126			{
127	3/4 ✓ Branch 0 taken 11396 times. ✓ Branch 1 taken 2898 times. ✗ Branch 2 not taken. ✓ Branch 3 taken 11396 times.	14445x	if (!this->ec_ && peer_impl_)
128		11501x	peer_.h_.reset(std::exchange(peer_impl_, nullptr));
129		14445x	return {this->ec_};
130			}
131			};
132
133			struct accept_value_awaitable : detail::void_op_base<accept_value_awaitable>
134			{
135			private:
136			friend tcp_acceptor;
137			friend detail::void_op_base<accept_value_awaitable>;
138
139			tcp_acceptor& acc_;
140		41x	mutable io_object::implementation* peer_impl_ = nullptr;
141
142
143		82x	explicit accept_value_awaitable(tcp_acceptor& acc) noexcept : acc_(acc)
144		41x	{
145		82x	}
146
147			std::coroutine_handle<>
148		37x	dispatch(capy::continuation& cont, capy::executor_ref ex) const
149			{
150	2/4 ✓ Branch 0 taken 37 times. ✗ Branch 1 not taken. ✓ Branch 2 taken 37 times. ✗ Branch 3 not taken.	74x	return acc_.get().accept(
151		37x	cont, ex, this->token_, &this->ec_, &peer_impl_);
152		✗	}
153
154			public:
155			// A peer accepted for an awaiter that never resumed is closed
156			// here, or nothing would own it.
157		164x	~accept_value_awaitable()
158		82x	{
159	2/2 ✓ Branch 0 taken 80 times. ✓ Branch 1 taken 2 times.	82x	if (peer_impl_)
160		2x	discard_peer(acc_, peer_impl_);
161		164x	}
162
163		31x	[[nodiscard]] capy::results<tcp_socket> await_resume() noexcept
164			{
165		31x	return take_peer(acc_, this->ec_, peer_impl_);
166			}
167			};
168
169			public:
170			/** Closes the acceptor if open, cancelling any pending operations.
171			*/
172			~tcp_acceptor() override;
173
174			/** Construct an acceptor from an execution context.
175
176			@param ctx The execution context that owns this acceptor.
177			*/
178			explicit tcp_acceptor(capy::execution_context& ctx);
179
180			/** Convenience constructor: open + configure + bind + listen.
181
182			Creates a fully bound listening acceptor in a single
183			expression, throwing the codes the piecewise `open()` +
184			`set_option()` + `bind()` + `listen()` path reports. The
185			address family is deduced from @p ep.
186
187			Before binding, the constructor configures address reuse so a
188			server can rebind its port immediately after a restart. It
189			sets `SO_REUSEADDR` on POSIX and `SO_EXCLUSIVEADDRUSE` on
190			Windows. Windows does not use `SO_REUSEADDR` because it
191			instead grants other sockets bind-over rights. A second
192			listener on an occupied endpoint therefore throws
193			`errc::address_in_use` on every platform.
194
195			@param ctx The execution context that owns this acceptor.
196			@param ep The local endpoint to bind to.
197			@param backlog The maximum pending connection queue length.
198
199			@throws std::system_error on open, configuration, bind, or
200			listen failure.
201			*/
202			tcp_acceptor(capy::execution_context& ctx, endpoint ep, int backlog = 128);
203
204			/** Construct an acceptor from an executor.
205
206			The acceptor is associated with the executor's context. `Ex`
207			must satisfy `capy::Executor`.
208
209			@param ex The executor whose context owns the acceptor.
210			*/
211			template<class Ex>
212			requires(!std::same_as<std::remove_cvref_t<Ex>, tcp_acceptor>) &&
213			capy::Executor<Ex>
214		1x	explicit tcp_acceptor(Ex const& ex) : tcp_acceptor(ex.context())
215			{
216		1x	}
217
218			/** Convenience constructor from an executor.
219
220			Creates a fully bound listening acceptor in a single
221			expression, throwing the codes the piecewise `open()` +
222			`set_option()` + `bind()` + `listen()` path reports. The
223			address family is deduced from @p ep.
224
225			Before binding, the constructor configures address reuse so a
226			server can rebind its port immediately after a restart. It
227			sets `SO_REUSEADDR` on POSIX and `SO_EXCLUSIVEADDRUSE` on
228			Windows. Windows does not use `SO_REUSEADDR` because it
229			instead grants other sockets bind-over rights. A second
230			listener on an occupied endpoint therefore throws
231			`errc::address_in_use` on every platform.
232
233			`Ex` must satisfy `capy::Executor`.
234
235			@param ex The executor whose context owns the acceptor.
236			@param ep The local endpoint to bind to.
237			@param backlog The maximum pending connection queue length.
238
239			@throws std::system_error on open, configuration, bind, or
240			listen failure.
241			*/
242			template<class Ex>
243			requires capy::Executor<Ex>
244			tcp_acceptor(Ex const& ex, endpoint ep, int backlog = 128)
245			: tcp_acceptor(ex.context(), ep, backlog)
246			{
247			}
248
249			/** Transfers ownership of the acceptor resources.
250
251			@param other The acceptor to move from.
252
253			@pre No awaitables returned by @p other's methods exist.
254			@pre The execution context associated with @p other must
255			outlive this acceptor.
256			*/
257		312x	tcp_acceptor(tcp_acceptor&& other) noexcept : io_object(std::move(other)) {}
258
259			/** Closes any existing acceptor and transfers ownership.
260
261			@param other The acceptor to move from.
262
263			@pre No awaitables returned by either `*this` or @p other's
264			methods exist.
265			@pre The execution context associated with @p other must
266			outlive this acceptor.
267
268			@return Reference to this acceptor.
269			*/
270		3x	tcp_acceptor& operator=(tcp_acceptor&& other) noexcept
271			{
272	1/2 ✗ Branch 0 not taken. ✓ Branch 1 taken 3 times.	3x	if (this != &other)
273			{
274		3x	close();
275		3x	h_ = std::move(other.h_);
276		3x	}
277		3x	return *this;
278			}
279
280			/// Copy construction is disabled; the handle is uniquely owned.
281			tcp_acceptor(tcp_acceptor const&) = delete;
282			/// Copy assignment is disabled; the handle is uniquely owned.
283			tcp_acceptor& operator=(tcp_acceptor const&) = delete;
284
285			/** Create the acceptor socket without binding or listening.
286
287			Creates a TCP socket with dual-stack enabled for IPv6.
288			Does not set SO_REUSEADDR. Call `set_option` explicitly
289			if needed.
290
291			If the acceptor is already open, this function is a no-op.
292
293			Failures such as descriptor exhaustion are normal runtime
294			conditions and are reported through the returned error code.
295
296			@param f The address family (IPv4 or IPv6). Defaults to
297			`family::v4`.
298
299			@par Example
300			@par !example open
301
302			@see @ref bind, @ref listen
303
304			@return The error code, empty on success.
305			*/
306			[[nodiscard]] std::error_code open(family f = family::v4) noexcept;
307
308			/** Bind to a local endpoint.
309
310			The acceptor must be open. Binds the socket to @p ep and
311			caches the resolved local endpoint (useful when port 0 is
312			used to request an ephemeral port).
313
314			@param ep The local endpoint to bind to.
315
316			@return An error code indicating success or the reason for
317			failure.
318
319			@par Error Conditions
320			@li `errc::address_in_use`: The endpoint is already in use.
321			@li `errc::address_not_available`: The address is not available
322			on any local interface.
323			@li `errc::permission_denied`: Insufficient privileges to bind
324			to the endpoint (e.g., privileged port).
325			@li `errc::bad_file_descriptor`: The acceptor is not open.
326			*/
327			[[nodiscard]] std::error_code bind(endpoint ep) noexcept;
328
329			/** Start listening for incoming connections.
330
331			The acceptor must be open and bound. Registers the acceptor
332			with the platform reactor.
333
334			@param backlog The maximum length of the queue of pending
335			connections. Defaults to 128.
336
337			@return An error code indicating success or the reason for
338			failure.
339
340			A closed acceptor reports `errc::bad_file_descriptor`.
341			*/
342			[[nodiscard]] std::error_code listen(int backlog = 128) noexcept;
343
344			/** Close the acceptor.
345
346			Releases acceptor resources. Any pending operations complete
347			with `errc::operation_canceled`.
348			*/
349			void close() noexcept;
350
351			/** Check if the acceptor is listening.
352
353			@return `true` if the acceptor is open and listening.
354			*/
355		38313x	bool is_open() const noexcept
356			{
357	2/2 ✓ Branch 0 taken 144 times. ✓ Branch 1 taken 37210 times.	38313x	return h_ && get().is_open();
358			}
359
360			/** Initiate an asynchronous accept operation.
361
362			Accepts an incoming connection and initializes the provided
363			socket with the new connection. The acceptor must be listening
364			before calling this function.
365
366			The operation supports cancellation via `std::stop_token` through
367			the affine awaitable protocol. If the associated stop token is
368			triggered, the operation completes immediately with
369			`errc::operation_canceled`.
370
371			@param peer The socket to receive the accepted connection. Any
372			existing connection on this socket is closed.
373
374			@return An awaitable that completes with `results<>`.
375			Returns success on successful accept, or an error code on
376			failure including:
377			- `operation_canceled`: Cancelled via stop_token or cancel().
378			Check `ec == cond::canceled` for portable comparison.
379
380			A closed acceptor completes with `errc::bad_file_descriptor`.
381
382			@pre The peer socket must be associated with the same execution context.
383
384			Both this acceptor and @p peer must outlive the returned
385			awaitable.
386
387			@par Example
388			@par !example accept_into_a_reused_socket
389
390			@see @ref accept()
391			*/
392		15257x	[[nodiscard]] auto accept(tcp_socket& peer)
393			{
394		15257x	accept_awaitable aw(*this, peer);
395	2/2 ✓ Branch 0 taken 15104 times. ✓ Branch 1 taken 2 times.	15257x	if (!is_open())
396		2x	aw.ec_ = make_error_code(std::errc::bad_file_descriptor);
397		15106x	return aw;
398		15106x	}
399
400			/** Initiate an asynchronous accept operation, returning the peer.
401
402			Accepts an incoming connection and returns a newly constructed
403			socket for it, associated with this acceptor's execution context.
404			The acceptor must be listening before calling this function.
405
406			The caller does not pre-construct the peer socket. The returned
407			socket shares this acceptor's execution context.
408
409			The operation supports cancellation via `std::stop_token` through
410			the affine awaitable protocol. If the associated stop token is
411			triggered, the operation completes immediately with
412			`errc::operation_canceled`.
413
414			@return An awaitable that completes with `results<tcp_socket>`.
415			On success the payload is the connected peer socket; on failure
416			(including cancellation) the error code is set and the payload
417			socket is unconnected. Errors include:
418			- `operation_canceled`: Cancelled via stop_token or cancel().
419			Check `ec == cond::canceled` for portable comparison.
420
421			A closed acceptor completes with `errc::bad_file_descriptor`.
422			On failure the returned socket is default-constructed and not
423			open. It has no context, so it may only be destroyed, assigned,
424			or checked with `is_open()`.
425
426			@pre This acceptor must outlive the returned awaitable.
427
428			@par Example
429			@par !example accept_returning_a_new_socket
430
431			@see @ref accept(tcp_socket&)
432			*/
433		41x	[[nodiscard]] auto accept()
434			{
435		41x	accept_value_awaitable aw(*this);
436	2/2 ✓ Branch 0 taken 37 times. ✓ Branch 1 taken 4 times.	41x	if (!is_open())
437		4x	aw.ec_ = make_error_code(std::errc::bad_file_descriptor);
438		41x	return aw;
439		41x	}
440
441			/** Wait for an incoming connection or readiness condition.
442
443			Suspends until the listen socket is ready in the
444			requested direction, or an error condition is reported.
445			For `wait_type::read`, completion signals that a
446			subsequent @ref accept succeeds without blocking. A
447			connection already queued when the wait begins completes
448			it immediately. No connection is consumed.
449
450			@note `wait_type::write` is not usable on an acceptor:
451			writability carries no meaning for a listening socket, so
452			the wait fails with `errc::operation_not_supported` on
453			every backend.
454
455			@param w The wait direction.
456
457			@return An awaitable that completes with `results<>`.
458
459			A closed acceptor completes with `errc::bad_file_descriptor`.
460
461			@pre This acceptor must outlive the returned awaitable.
462			*/
463		31x	[[nodiscard]] auto wait(wait_type w)
464			{
465		31x	wait_awaitable aw(*this, w);
466	2/2 ✓ Branch 0 taken 29 times. ✓ Branch 1 taken 2 times.	31x	if (!is_open())
467		2x	aw.ec_ = make_error_code(std::errc::bad_file_descriptor);
468		31x	return aw;
469		31x	}
470
471			/** Cancel any pending asynchronous operations.
472
473			Accept and wait transfer no bytes, so a cancellation always wins:
474			an operation reports `errc::operation_canceled` even when it had
475			already succeeded when the cancellation landed. Check
476			`ec == cond::canceled` for portable comparison.
477			*/
478			void cancel() noexcept;
479
480			/** Get the native socket handle.
481
482			Returns the underlying platform-specific socket descriptor.
483			On POSIX systems this is an `int` file descriptor.
484			On Windows this is a `SOCKET` handle.
485
486			@return The native socket handle, or -1/INVALID_SOCKET if not open.
487
488			@pre None. May be called on closed acceptors.
489			*/
490			native_handle_type native_handle() const noexcept;
491
492			/** Assign an existing native socket to this acceptor.
493
494			Adopts a listening socket created outside the library. The
495			socket may come from a service manager, be inherited, or be
496			created natively. Adoption registers the socket with the
497			backend. The socket must be a listening stream socket in the
498			`AF_INET` or `AF_INET6` family.
499			Adoption never alters the descriptor's flags or options: on
500			POSIX the fd must already be non-blocking, and on Windows the
501			socket must be overlapped-capable.
502
503			Adoption does not verify listen state; @ref accept reports the
504			error if the socket is not listening.
505
506			The object must be closed. To replace a held socket, `close()`
507			or `release()` it first.
508
509			@par Exception Safety
510			Throws nothing. On failure the object is unchanged and the
511			caller retains ownership of `fd`.
512
513			@param fd The native socket to adopt. On success the object
514			owns it and closes it.
515
516			@return `error::already_open` if this object is open.
517			Otherwise the error code, empty on success. Validation and
518			registration failures are normal runtime conditions when
519			adopting foreign descriptors.
520			*/
521			[[nodiscard]] std::error_code assign(native_handle_type fd) noexcept;
522
523			/** Release ownership of the native socket handle.
524
525			Deregisters the socket from the backend and cancels pending
526			operations without closing the descriptor. The caller takes
527			ownership of the returned handle.
528
529			A closed object reports `errc::bad_file_descriptor` and the
530			returned handle is the invalid sentinel ( -1, or
531			`INVALID_SOCKET` on Windows ), never zero.
532
533			@note With the IOCP backend, a socket released while operations
534			on it are in flight stays bound to this context's completion
535			port for good. Windows refuses to unbind a handle with I/O
536			outstanding, so no context, this one included, can assign it
537			afterwards. Its cancelled operations still complete normally.
538
539			@return The error code and the native handle.
540
541			@post is_open() == false
542			*/
543			[[nodiscard]] capy::results<native_handle_type> release() noexcept;
544
545			/** Get the local endpoint of the acceptor.
546
547			Returns the local address and port to which the acceptor is bound.
548			This is useful when binding to port 0 (ephemeral port) to discover
549			the OS-assigned port number. The endpoint is cached when bind()
550			is called.
551
552			@return The local endpoint, or a default endpoint (0.0.0.0:0) if
553			the acceptor is not open.
554
555			@par Thread Safety
556			The cached endpoint value is set during bind() and cleared
557			during close(). This function may be called concurrently with
558			accept operations, but must not be called concurrently with
559			bind() or close().
560			*/
561			endpoint local_endpoint() const noexcept;
562
563			/** Set a socket option on the acceptor.
564
565			Applies a type-safe socket option to the underlying listening
566			socket. The socket must be open (via `open()` or `listen()`).
567			This is useful for setting options between `open()` and
568			`listen()`, such as `socket_option::reuse_port`.
569
570			Fails with `errc::bad_file_descriptor` if the acceptor is not
571			open, or with the error the operating system reports.
572
573			@par Example
574			@par !example set_option
575
576			@param opt The option to set.
577
578			@return The error code, empty on success.
579			*/
580			template<class Option>
581		2752x	[[nodiscard]] std::error_code set_option(Option const& opt) noexcept
582			{
583	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 2739 times. ✗ Branch 2 not taken. ✓ Branch 3 taken 9 times. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	2752x	if (!is_open())
584		2x	return make_error_code(std::errc::bad_file_descriptor);
585		2750x	auto const fam = get().family();
586		5500x	return get().set_option(
587		2750x	opt.level(fam), opt.name(fam), opt.data(fam), opt.size(fam));
588		2752x	}
589
590			/** Get a socket option from the acceptor.
591
592			Retrieves the current value of a type-safe socket option.
593
594			Fails with `errc::bad_file_descriptor` if the acceptor is not
595			open, or with the error the operating system reports. On
596			failure the option is value-initialized.
597
598			@par Example
599			@par !example get_option
600
601			@return The error code and the option value.
602			*/
603			template<class Option>
604		15x	[[nodiscard]] capy::results<Option> get_option() const noexcept
605			{
606	4/6 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 9 times. ✗ Branch 2 not taken. ✓ Branch 3 taken 2 times. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times.	15x	if (!is_open())
607		2x	return {make_error_code(std::errc::bad_file_descriptor), Option{}};
608		13x	Option opt{};
609		13x	auto const fam = get().family();
610		13x	std::size_t sz = opt.size(fam);
611	8/12 ✓ Branch 0 taken 2 times. ✓ Branch 1 taken 7 times. ✓ Branch 2 taken 2 times. ✓ Branch 3 taken 7 times. ✗ Branch 4 not taken. ✓ Branch 5 taken 2 times. ✗ Branch 6 not taken. ✓ Branch 7 taken 2 times. ✓ Branch 8 taken 2 times. ✗ Branch 9 not taken. ✓ Branch 10 taken 2 times. ✗ Branch 11 not taken.	26x	if (auto ec = get().get_option(
612		13x	opt.level(fam), opt.name(fam), opt.data(fam), &sz))
613		4x	return {ec, Option{}};
614		9x	opt.resize(fam, sz);
615		9x	return {std::error_code{}, std::move(opt)};
616		15x	}
617
618			/** Define backend hooks for TCP acceptor operations.
619
620			Platform backends derive from this to implement
621			accept, endpoint query, open-state checks, cancellation,
622			and socket-option management.
623			*/
624			struct implementation : io_object::implementation
625			{
626			/** Initiate an asynchronous accept operation.
627
628			@param cont Continuation to resume on completion; it lives in
629			the awaiting frame until then.
630			@param ex Executor for dispatching the completion.
631			@param token Stop token for cancellation.
632			@param ec Output error code.
633			@param impl_out Output implementation for the accepted peer.
634
635			@return Coroutine handle to resume immediately.
636			*/
637			virtual std::coroutine_handle<> accept(
638			capy::continuation& cont,
639			capy::executor_ref ex,
640			std::stop_token token,
641			std::error_code* ec,
642			io_object::implementation** impl_out) = 0;
643
644			/** Initiate an asynchronous wait for acceptor readiness.
645
646			Completes when the listen socket becomes ready for
647			the specified direction (typically `wait_type::read`
648			for an incoming connection), or an error condition is
649			reported. No connection is consumed.
650
651			@param cont Continuation to resume on completion; it lives in
652			the awaiting frame until then.
653			@param ex Executor for dispatching the completion.
654			@param w The direction to wait on.
655			@param token Stop token for cancellation.
656			@param ec Output error code.
657
658			@return Coroutine handle to resume immediately.
659			*/
660			virtual std::coroutine_handle<> wait(
661			capy::continuation& cont,
662			capy::executor_ref ex,
663			wait_type w,
664			std::stop_token token,
665			std::error_code* ec) = 0;
666
667			/** Returns the cached local endpoint.
668
669			@return The cached local endpoint.
670			*/
671			virtual endpoint local_endpoint() const noexcept = 0;
672
673			/** Return true if the acceptor has a kernel resource open.
674
675			@return true if the acceptor has a kernel resource open.
676			*/
677			virtual bool is_open() const noexcept = 0;
678
679			/** Return the native handle, or the platform sentinel if closed.
680
681			@return The native handle, or the platform sentinel if closed.
682			*/
683			virtual native_handle_type native_handle() const noexcept = 0;
684
685			/** Return the socket's address family.
686
687			Socket options render for this family.
688
689			@return The socket's address family.
690			*/
691			virtual corosio::family family() const noexcept = 0;
692
693			/** Release and return the native handle without closing.
694
695			@return The native handle.
696			*/
697			virtual native_handle_type release_socket() noexcept = 0;
698
699			/** Cancel any pending asynchronous operations.
700
701			Accept and wait transfer no bytes, so a cancellation always
702			wins: an operation reports `operation_canceled` even when it
703			had already succeeded when the cancellation landed.
704			*/
705			virtual void cancel() noexcept = 0;
706
707			/** Set a socket option.
708
709			@param level The protocol level.
710			@param optname The option name.
711			@param data Pointer to the option value.
712			@param size Size of the option value in bytes.
713			@return Error code on failure, empty on success.
714			*/
715			virtual std::error_code set_option(
716			int level,
717			int optname,
718			void const* data,
719			std::size_t size) noexcept = 0;
720
721			/** Get a socket option.
722
723			@param level The protocol level.
724			@param optname The option name.
725			@param data Pointer to receive the option value.
726			@param size On entry, the size of the buffer. On exit,
727			the size of the option value.
728			@return Error code on failure, empty on success.
729			*/
730			virtual std::error_code
731			get_option(int level, int optname, void* data, std::size_t* size)
732			const noexcept = 0;
733			};
734
735			protected:
736			/** Adopt an existing handle.
737
738			@param h The handle the acceptor takes ownership of.
739			*/
740		51x	explicit tcp_acceptor(handle h) noexcept : io_object(std::move(h)) {}
741
742			/** Adopt an existing handle, then open, configure, bind, and listen.
743
744			Lets a derived acceptor offer the convenience constructor while
745			supplying its own service.
746
747			@param h The handle the acceptor takes ownership of.
748			@param ep The local endpoint to bind to.
749			@param backlog The maximum pending connection queue length.
750
751			@throws std::system_error on open, configuration, bind, or
752			listen failure.
753			*/
754			tcp_acceptor(handle h, endpoint ep, int backlog);
755
756			/** Transfer the accepted peer implementation to the peer socket.
757
758			@param peer The socket that receives the transferred implementation.
759			@param impl The accepted peer implementation, or null to do nothing.
760			*/
761			static void
762		19x	reset_peer_impl(tcp_socket& peer, io_object::implementation* impl) noexcept
763			{
764	1/2 ✗ Branch 0 not taken. ✓ Branch 1 taken 19 times.	19x	if (impl)
765		19x	peer.h_.reset(impl);
766		19x	}
767
768			/** Return the result of an accept that yields the peer.
769
770			The peer socket is built only on success, so a failed accept
771			never touches the acceptor's context, which a moved-from
772			acceptor lacks. On failure the peer is default-constructed.
773
774			@param acc The acceptor that performed the accept.
775			@param ec The completion code.
776			@param impl The accepted peer implementation; taken on success.
777
778			@return The completion code and the peer.
779			*/
780		39x	static capy::results<tcp_socket> take_peer(
781			tcp_acceptor& acc,
782			std::error_code ec,
783			io_object::implementation*& impl) noexcept
784			{
785	3/4 ✓ Branch 0 taken 27 times. ✓ Branch 1 taken 12 times. ✗ Branch 2 not taken. ✓ Branch 3 taken 27 times.	39x	if (ec \|\| !impl)
786		12x	return {ec, tcp_socket()};
787
788	1/2 ✓ Branch 0 taken 27 times. ✗ Branch 1 not taken.	27x	tcp_socket peer(acc.context());
789		27x	peer.h_.reset(std::exchange(impl, nullptr));
790		27x	return {ec, std::move(peer)};
791		39x	}
792
793			/// Close and release a non-null accepted peer no socket took over.
794			static void
795			discard_peer(tcp_acceptor& acc, io_object::implementation* impl) noexcept;
796
797			private:
798		61748x	inline implementation& get() const noexcept
799			{
800		61748x	return static_cast<implementation>(h_.get());
801			}
802			};
803
804			} // namespace boost::corosio
805
806			#endif
807