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_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/except.hpp>
18 : #include <boost/corosio/detail/native_handle.hpp>
19 : #include <boost/corosio/detail/op_base.hpp>
20 : #include <boost/corosio/wait_type.hpp>
21 : #include <boost/corosio/io/io_object.hpp>
22 : #include <boost/capy/io_result.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/io_env.hpp>
28 : #include <boost/capy/concept/executor.hpp>
29 :
30 : #include <system_error>
31 :
32 : #include <concepts>
33 : #include <coroutine>
34 : #include <cstddef>
35 : #include <stop_token>
36 : #include <type_traits>
37 :
38 : namespace boost::corosio {
39 :
40 : /** An asynchronous TCP acceptor for coroutine I/O.
41 :
42 : This class provides asynchronous TCP accept operations that return
43 : awaitable types. The acceptor binds to a local endpoint and listens
44 : for incoming connections.
45 :
46 : Each accept operation participates in the affine awaitable protocol,
47 : ensuring coroutines resume on the correct executor.
48 :
49 : @par Thread Safety
50 : Distinct objects: Safe.@n
51 : Shared objects: Unsafe. An acceptor must not have concurrent accept
52 : operations.
53 :
54 : @par Semantics
55 : Wraps the platform TCP listener. Operations dispatch to
56 : OS accept APIs via the io_context reactor.
57 :
58 : @par Example
59 : @par !example convenience_construction
60 :
61 : @par Example
62 : @par !example fine_grained_setup
63 : */
64 : class BOOST_COROSIO_DECL tcp_acceptor : public io_object
65 : {
66 : struct wait_awaitable : detail::void_op_base<wait_awaitable>
67 : {
68 : tcp_acceptor& acc_;
69 : wait_type w_;
70 :
71 HIT 28 : wait_awaitable(tcp_acceptor& acc, wait_type w) noexcept
72 56 : : acc_(acc)
73 28 : , w_(w)
74 : {
75 28 : }
76 :
77 : std::coroutine_handle<>
78 24 : dispatch(std::coroutine_handle<> h, capy::executor_ref ex) const
79 : {
80 24 : return acc_.get().wait(h, ex, w_, token_, &ec_);
81 : }
82 : };
83 :
84 : struct accept_awaitable : detail::void_op_base<accept_awaitable>
85 : {
86 : tcp_acceptor& acc_;
87 : tcp_socket& peer_;
88 : mutable io_object::implementation* peer_impl_ = nullptr;
89 :
90 4522 : accept_awaitable(tcp_acceptor& acc, tcp_socket& peer) noexcept
91 9044 : : acc_(acc)
92 4522 : , peer_(peer)
93 : {
94 4522 : }
95 :
96 4512 : [[nodiscard]] capy::io_result<> await_resume() const noexcept
97 : {
98 4512 : if (!this->ec_ && peer_impl_)
99 4417 : peer_.h_.reset(peer_impl_);
100 4512 : return {this->ec_};
101 : }
102 :
103 : std::coroutine_handle<>
104 4518 : dispatch(std::coroutine_handle<> h, capy::executor_ref ex) const
105 : {
106 13554 : return acc_.get().accept(
107 13554 : h, ex, this->token_, &this->ec_, &peer_impl_);
108 : }
109 : };
110 :
111 : struct accept_value_awaitable : detail::void_op_base<accept_value_awaitable>
112 : {
113 : tcp_acceptor& acc_;
114 : mutable io_object::implementation* peer_impl_ = nullptr;
115 :
116 33 : explicit accept_value_awaitable(tcp_acceptor& acc) noexcept : acc_(acc)
117 : {
118 33 : }
119 :
120 33 : [[nodiscard]] capy::io_result<tcp_socket> await_resume() noexcept
121 : {
122 : // The peer is built only on success: error paths must not
123 : // touch acc_.context(), which a moved-from acceptor lacks.
124 33 : if (this->ec_ || !peer_impl_)
125 6 : return {this->ec_, tcp_socket()};
126 :
127 27 : tcp_socket peer(acc_.context());
128 27 : peer.h_.reset(peer_impl_);
129 27 : return {this->ec_, std::move(peer)};
130 27 : }
131 :
132 : std::coroutine_handle<>
133 29 : dispatch(std::coroutine_handle<> h, capy::executor_ref ex) const
134 : {
135 87 : return acc_.get().accept(
136 87 : h, ex, this->token_, &this->ec_, &peer_impl_);
137 : }
138 : };
139 :
140 : public:
141 : /** Destructor.
142 :
143 : Closes the acceptor if open, cancelling any pending operations.
144 : */
145 : ~tcp_acceptor() override;
146 :
147 : /** Construct an acceptor from an execution context.
148 :
149 : @param ctx The execution context that will own this acceptor.
150 : */
151 : explicit tcp_acceptor(capy::execution_context& ctx);
152 :
153 : /** Convenience constructor: open + configure + bind + listen.
154 :
155 : Creates a fully-bound listening acceptor in a single
156 : expression, throwing the codes the piecewise `open()` +
157 : `set_option()` + `bind()` + `listen()` path reports. The
158 : address family is deduced from @p ep.
159 :
160 : Before binding, the constructor configures address reuse so
161 : a server can rebind its port immediately after a restart:
162 : `SO_REUSEADDR` on POSIX, `SO_EXCLUSIVEADDRUSE` on Windows
163 : ( where `SO_REUSEADDR` instead grants other sockets
164 : bind-over rights ). A second listener on an occupied
165 : endpoint therefore throws `errc::address_in_use` on every
166 : platform.
167 :
168 : @param ctx The execution context that will own this acceptor.
169 : @param ep The local endpoint to bind to.
170 : @param backlog The maximum pending connection queue length.
171 :
172 : @throws std::system_error on open, configuration, bind, or
173 : listen failure.
174 : */
175 : tcp_acceptor(capy::execution_context& ctx, endpoint ep, int backlog = 128);
176 :
177 : /** Construct an acceptor from an executor.
178 :
179 : The acceptor is associated with the executor's context.
180 :
181 : @param ex The executor whose context will own the acceptor.
182 : */
183 : template<class Ex>
184 : requires(!std::same_as<std::remove_cvref_t<Ex>, tcp_acceptor>) &&
185 : capy::Executor<Ex>
186 1 : explicit tcp_acceptor(Ex const& ex) : tcp_acceptor(ex.context())
187 : {
188 1 : }
189 :
190 : /** Convenience constructor from an executor.
191 :
192 : @param ex The executor whose context will own the acceptor.
193 : @param ep The local endpoint to bind to.
194 : @param backlog The maximum pending connection queue length.
195 :
196 : @throws std::system_error on open, configuration, bind, or
197 : listen failure.
198 : */
199 : template<class Ex>
200 : requires capy::Executor<Ex>
201 : tcp_acceptor(Ex const& ex, endpoint ep, int backlog = 128)
202 : : tcp_acceptor(ex.context(), ep, backlog)
203 : {
204 : }
205 :
206 : /** Move constructor.
207 :
208 : Transfers ownership of the acceptor resources.
209 :
210 : @param other The acceptor to move from.
211 :
212 : @pre No awaitables returned by @p other's methods exist.
213 : @pre The execution context associated with @p other must
214 : outlive this acceptor.
215 : */
216 9 : tcp_acceptor(tcp_acceptor&& other) noexcept : io_object(std::move(other)) {}
217 :
218 : /** Move assignment operator.
219 :
220 : Closes any existing acceptor and transfers ownership.
221 :
222 : @param other The acceptor to move from.
223 :
224 : @pre No awaitables returned by either `*this` or @p other's
225 : methods exist.
226 : @pre The execution context associated with @p other must
227 : outlive this acceptor.
228 :
229 : @return Reference to this acceptor.
230 : */
231 3 : tcp_acceptor& operator=(tcp_acceptor&& other) noexcept
232 : {
233 3 : if (this != &other)
234 : {
235 3 : close();
236 3 : h_ = std::move(other.h_);
237 : }
238 3 : return *this;
239 : }
240 :
241 : tcp_acceptor(tcp_acceptor const&) = delete;
242 : tcp_acceptor& operator=(tcp_acceptor const&) = delete;
243 :
244 : /** Create the acceptor socket without binding or listening.
245 :
246 : Creates a TCP socket with dual-stack enabled for IPv6.
247 : Does not set SO_REUSEADDR — call `set_option` explicitly
248 : if needed.
249 :
250 : If the acceptor is already open, this function is a no-op.
251 :
252 : Failures such as descriptor exhaustion are normal runtime
253 : conditions and are reported through the returned error code.
254 :
255 : @param f The address family (IPv4 or IPv6). Defaults to
256 : `family::v4`.
257 :
258 : @par Example
259 : @par !example open
260 :
261 : @see bind, listen
262 :
263 : @return The error code, empty on success.
264 : */
265 : [[nodiscard]] std::error_code open(family f = family::v4) noexcept;
266 :
267 : /** Bind to a local endpoint.
268 :
269 : The acceptor must be open. Binds the socket to @p ep and
270 : caches the resolved local endpoint (useful when port 0 is
271 : used to request an ephemeral port).
272 :
273 : @param ep The local endpoint to bind to.
274 :
275 : @return An error code indicating success or the reason for
276 : failure.
277 :
278 : @par Error Conditions
279 : @li `errc::address_in_use`: The endpoint is already in use.
280 : @li `errc::address_not_available`: The address is not available
281 : on any local interface.
282 : @li `errc::permission_denied`: Insufficient privileges to bind
283 : to the endpoint (e.g., privileged port).
284 :
285 : A closed acceptor reports `errc::bad_file_descriptor`.
286 : */
287 : [[nodiscard]] std::error_code bind(endpoint ep) noexcept;
288 :
289 : /** Start listening for incoming connections.
290 :
291 : The acceptor must be open and bound. Registers the acceptor
292 : with the platform reactor.
293 :
294 : @param backlog The maximum length of the queue of pending
295 : connections. Defaults to 128.
296 :
297 : @return An error code indicating success or the reason for
298 : failure.
299 :
300 : A closed acceptor reports `errc::bad_file_descriptor`.
301 : */
302 : [[nodiscard]] std::error_code listen(int backlog = 128) noexcept;
303 :
304 : /** Close the acceptor.
305 :
306 : Releases acceptor resources. Any pending operations complete
307 : with `errc::operation_canceled`.
308 : */
309 : void close() noexcept;
310 :
311 : /** Check if the acceptor is listening.
312 :
313 : @return `true` if the acceptor is open and listening.
314 : */
315 8841 : bool is_open() const noexcept
316 : {
317 8841 : return h_ && get().is_open();
318 : }
319 :
320 : /** Initiate an asynchronous accept operation.
321 :
322 : Accepts an incoming connection and initializes the provided
323 : socket with the new connection. The acceptor must be listening
324 : before calling this function.
325 :
326 : The operation supports cancellation via `std::stop_token` through
327 : the affine awaitable protocol. If the associated stop token is
328 : triggered, the operation completes immediately with
329 : `errc::operation_canceled`.
330 :
331 : @param peer The socket to receive the accepted connection. Any
332 : existing connection on this socket will be closed.
333 :
334 : @return An awaitable that completes with `io_result<>`.
335 : Returns success on successful accept, or an error code on
336 : failure including:
337 : - operation_canceled: Cancelled via stop_token or cancel().
338 : Check `ec == cond::canceled` for portable comparison.
339 :
340 : A closed acceptor completes with `errc::bad_file_descriptor`.
341 :
342 : @par Preconditions
343 : The peer socket must be associated with the same execution context.
344 :
345 : Both this acceptor and @p peer must outlive the returned
346 : awaitable.
347 :
348 : @par Example
349 : @par !example accept_into_a_reused_socket
350 :
351 : @see accept()
352 : */
353 4522 : [[nodiscard]] auto accept(tcp_socket& peer)
354 : {
355 4522 : accept_awaitable aw(*this, peer);
356 4522 : if (!is_open())
357 2 : aw.ec_ = make_error_code(std::errc::bad_file_descriptor);
358 4522 : return aw;
359 : }
360 :
361 : /** Initiate an asynchronous accept operation, returning the peer.
362 :
363 : Accepts an incoming connection and returns a newly constructed
364 : socket for it, associated with this acceptor's execution context.
365 : The acceptor must be listening before calling this function.
366 :
367 : The caller does not pre-construct the peer socket; the returned
368 : socket shares this acceptor's execution context.
369 :
370 : The operation supports cancellation via `std::stop_token` through
371 : the affine awaitable protocol. If the associated stop token is
372 : triggered, the operation completes immediately with
373 : `errc::operation_canceled`.
374 :
375 : @return An awaitable that completes with `io_result<tcp_socket>`.
376 : On success the payload is the connected peer socket; on failure
377 : (including cancellation) the error code is set and the payload
378 : socket is unconnected. Errors include:
379 : - operation_canceled: Cancelled via stop_token or cancel().
380 : Check `ec == cond::canceled` for portable comparison.
381 :
382 : A closed acceptor completes with `errc::bad_file_descriptor`.
383 : On failure the returned socket is default-constructed and
384 : may only be destroyed or assigned.
385 :
386 : @par Preconditions
387 : This acceptor must outlive the returned awaitable.
388 :
389 : @par Example
390 : @par !example accept_returning_a_new_socket
391 :
392 : @see accept(tcp_socket&)
393 : */
394 33 : [[nodiscard]] auto accept()
395 : {
396 33 : accept_value_awaitable aw(*this);
397 33 : if (!is_open())
398 4 : aw.ec_ = make_error_code(std::errc::bad_file_descriptor);
399 33 : return aw;
400 : }
401 :
402 : /** Wait for an incoming connection or readiness condition.
403 :
404 : Suspends until the listen socket is ready in the
405 : requested direction, or an error condition is reported.
406 : For `wait_type::read`, completion signals that a
407 : subsequent @ref accept will succeed without blocking; a
408 : connection already queued when the wait begins completes
409 : it immediately. No connection is consumed.
410 :
411 : @note `wait_type::write` is not usable on an acceptor:
412 : writability carries no meaning for a listening socket, so
413 : the wait fails with `errc::operation_not_supported` on
414 : every backend.
415 :
416 : @param w The wait direction.
417 :
418 : @return An awaitable that completes with `io_result<>`.
419 :
420 : A closed acceptor completes with `errc::bad_file_descriptor`.
421 :
422 : @par Preconditions
423 : This acceptor must outlive the returned awaitable.
424 : */
425 28 : [[nodiscard]] auto wait(wait_type w)
426 : {
427 28 : wait_awaitable aw(*this, w);
428 28 : if (!is_open())
429 2 : aw.ec_ = make_error_code(std::errc::bad_file_descriptor);
430 28 : return aw;
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 : @par Preconditions
450 : None. May be called on closed acceptors.
451 : */
452 : native_handle_type native_handle() const noexcept;
453 :
454 : /** Assign an existing native socket to this acceptor.
455 :
456 : Adopts a listening socket created outside the library —
457 : received from a service manager, inherited, or made natively —
458 : and registers it with the backend. The socket must be a
459 : listening stream socket in the `AF_INET` or `AF_INET6` family.
460 : Adoption never alters the descriptor's flags or options: on
461 : POSIX the fd must already be non-blocking, and on Windows the
462 : socket must be overlapped-capable.
463 :
464 : Adoption does not verify listen state; @ref accept reports the
465 : error if the socket is not listening.
466 :
467 : If this object is already open, pending operations complete
468 : with `errc::operation_canceled` and the held socket is
469 : closed before the new one is adopted.
470 :
471 : @par Exception Safety
472 : Strong guarantee on validation failure: the object is
473 : unchanged. If backend registration fails, the object either
474 : retains its previous socket or is left closed, depending on
475 : the backend. In all failure cases the caller retains
476 : ownership of `fd`.
477 :
478 : @param fd The native socket to adopt. On success the object
479 : owns it and will close it.
480 :
481 : @return The error code, empty on success. Validation and
482 : registration failures are normal runtime conditions when
483 : adopting foreign descriptors.
484 : */
485 : [[nodiscard]] std::error_code assign(native_handle_type fd) noexcept;
486 :
487 : /** Release ownership of the native socket handle.
488 :
489 : Deregisters the socket from the backend and cancels pending
490 : operations without closing the descriptor. The caller takes
491 : ownership of the returned handle.
492 :
493 : @return The native handle.
494 :
495 : @throws std::system_error `errc::bad_file_descriptor` if the
496 : acceptor is not open.
497 :
498 : @post is_open() == false
499 : */
500 : native_handle_type release();
501 :
502 : /** Get the local endpoint of the acceptor.
503 :
504 : Returns the local address and port to which the acceptor is bound.
505 : This is useful when binding to port 0 (ephemeral port) to discover
506 : the OS-assigned port number. The endpoint is cached when bind()
507 : is called.
508 :
509 : @return The local endpoint, or a default endpoint (0.0.0.0:0) if
510 : the acceptor is not open.
511 :
512 : @par Thread Safety
513 : The cached endpoint value is set during bind() and cleared
514 : during close(). This function may be called concurrently with
515 : accept operations, but must not be called concurrently with
516 : bind() or close().
517 : */
518 : endpoint local_endpoint() const noexcept;
519 :
520 : /** Set a socket option on the acceptor.
521 :
522 : Applies a type-safe socket option to the underlying listening
523 : socket. The socket must be open (via `open()` or `listen()`).
524 : This is useful for setting options between `open()` and
525 : `listen()`, such as `socket_option::reuse_port`.
526 :
527 : @par Example
528 : @par !example set_option
529 :
530 : @param opt The option to set.
531 :
532 : @throws std::system_error `errc::bad_file_descriptor` if the
533 : acceptor is not open; otherwise thrown on failure.
534 : */
535 : template<class Option>
536 609 : void set_option(Option const& opt)
537 : {
538 609 : if (!is_open())
539 2 : detail::throw_system_error(
540 4 : make_error_code(std::errc::bad_file_descriptor),
541 : "tcp_acceptor::set_option");
542 607 : auto const fam = get().family();
543 607 : std::error_code ec = get().set_option(
544 : opt.level(fam), opt.name(fam), opt.data(fam), opt.size(fam));
545 607 : if (ec)
546 8 : detail::throw_system_error(ec, "tcp_acceptor::set_option");
547 599 : }
548 :
549 : /** Get a socket option from the acceptor.
550 :
551 : Retrieves the current value of a type-safe socket option.
552 :
553 : @par Example
554 : @par !example get_option
555 :
556 : @return The current option value.
557 :
558 : @throws std::system_error `errc::bad_file_descriptor` if the
559 : acceptor is not open; otherwise thrown on failure.
560 : */
561 : template<class Option>
562 23 : Option get_option() const
563 : {
564 23 : if (!is_open())
565 2 : detail::throw_system_error(
566 4 : make_error_code(std::errc::bad_file_descriptor),
567 : "tcp_acceptor::get_option");
568 21 : Option opt{};
569 21 : auto const fam = get().family();
570 21 : std::size_t sz = opt.size(fam);
571 : std::error_code ec =
572 21 : get().get_option(opt.level(fam), opt.name(fam), opt.data(fam), &sz);
573 21 : if (ec)
574 8 : detail::throw_system_error(ec, "tcp_acceptor::get_option");
575 13 : opt.resize(fam, sz);
576 13 : return opt;
577 : }
578 :
579 : /** Define backend hooks for TCP acceptor operations.
580 :
581 : Platform backends derive from this to implement
582 : accept, endpoint query, open-state checks, cancellation,
583 : and socket-option management.
584 : */
585 : struct implementation : io_object::implementation
586 : {
587 : /// Initiate an asynchronous accept operation.
588 : virtual std::coroutine_handle<> accept(
589 : std::coroutine_handle<>,
590 : capy::executor_ref,
591 : std::stop_token,
592 : std::error_code*,
593 : io_object::implementation**) = 0;
594 :
595 : /** Initiate an asynchronous wait for acceptor readiness.
596 :
597 : Completes when the listen socket becomes ready for
598 : the specified direction (typically `wait_type::read`
599 : for an incoming connection), or an error condition is
600 : reported. No connection is consumed.
601 : */
602 : virtual std::coroutine_handle<> wait(
603 : std::coroutine_handle<> h,
604 : capy::executor_ref ex,
605 : wait_type w,
606 : std::stop_token token,
607 : std::error_code* ec) = 0;
608 :
609 : /// Returns the cached local endpoint.
610 : virtual endpoint local_endpoint() const noexcept = 0;
611 :
612 : /// Return true if the acceptor has a kernel resource open.
613 : virtual bool is_open() const noexcept = 0;
614 :
615 : /// Return the native handle, or the platform sentinel if closed.
616 : virtual native_handle_type native_handle() const noexcept = 0;
617 :
618 : /** Return the socket's address family.
619 :
620 : Socket options render for this family.
621 :
622 : @return The socket's address family.
623 : */
624 : virtual corosio::family family() const noexcept = 0;
625 :
626 : /// Release and return the native handle without closing.
627 : virtual native_handle_type release_socket() noexcept = 0;
628 :
629 : /** Cancel any pending asynchronous operations.
630 :
631 : Operations still in flight complete with `operation_canceled`;
632 : an operation whose result is already decided reports that
633 : result.
634 : */
635 : virtual void cancel() noexcept = 0;
636 :
637 : /** Set a socket option.
638 :
639 : @param level The protocol level.
640 : @param optname The option name.
641 : @param data Pointer to the option value.
642 : @param size Size of the option value in bytes.
643 : @return Error code on failure, empty on success.
644 : */
645 : virtual std::error_code set_option(
646 : int level,
647 : int optname,
648 : void const* data,
649 : std::size_t size) noexcept = 0;
650 :
651 : /** Get a socket option.
652 :
653 : @param level The protocol level.
654 : @param optname The option name.
655 : @param data Pointer to receive the option value.
656 : @param size On entry, the size of the buffer. On exit,
657 : the size of the option value.
658 : @return Error code on failure, empty on success.
659 : */
660 : virtual std::error_code
661 : get_option(int level, int optname, void* data, std::size_t* size)
662 : const noexcept = 0;
663 : };
664 :
665 : protected:
666 35 : explicit tcp_acceptor(handle h) noexcept : io_object(std::move(h)) {}
667 :
668 : /// Transfer accepted peer impl to the peer socket.
669 : static void
670 17 : reset_peer_impl(tcp_socket& peer, io_object::implementation* impl) noexcept
671 : {
672 17 : if (impl)
673 17 : peer.h_.reset(impl);
674 17 : }
675 :
676 : private:
677 15246 : inline implementation& get() const noexcept
678 : {
679 15246 : return *static_cast<implementation*>(h_.get());
680 : }
681 : };
682 :
683 : } // namespace boost::corosio
684 :
685 : #endif
|
