TLA Line data Source code
1 : //
2 : // Copyright (c) 2026 Michael Vandeberg
3 : //
4 : // Distributed under the Boost Software License, Version 1.0. (See accompanying
5 : // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6 : //
7 : // Official repository: https://github.com/cppalliance/corosio
8 : //
9 :
10 : #ifndef BOOST_COROSIO_LOCAL_DATAGRAM_SOCKET_HPP
11 : #define BOOST_COROSIO_LOCAL_DATAGRAM_SOCKET_HPP
12 :
13 : #include <boost/corosio/family.hpp>
14 : #include <boost/corosio/detail/config.hpp>
15 : #include <boost/corosio/detail/platform.hpp>
16 :
17 : #if BOOST_COROSIO_POSIX
18 :
19 : #include <boost/corosio/detail/native_handle.hpp>
20 : #include <boost/corosio/detail/op_base.hpp>
21 : #include <boost/corosio/io/io_object.hpp>
22 : #include <boost/capy/results.hpp>
23 : #include <boost/corosio/detail/buffer_param.hpp>
24 : #include <boost/corosio/error.hpp>
25 : #include <boost/corosio/local_endpoint.hpp>
26 : #include <boost/corosio/message_flags.hpp>
27 : #include <boost/corosio/shutdown_type.hpp>
28 : #include <boost/corosio/wait_type.hpp>
29 : #include <boost/capy/ex/executor_ref.hpp>
30 : #include <boost/capy/ex/execution_context.hpp>
31 : #include <boost/capy/ex/await_context.hpp>
32 : #include <boost/capy/concept/executor.hpp>
33 :
34 : #include <system_error>
35 :
36 : #include <concepts>
37 : #include <boost/capy/continuation.hpp>
38 :
39 : #include <coroutine>
40 : #include <cstddef>
41 : #include <stop_token>
42 : #include <type_traits>
43 : #include <utility>
44 :
45 : namespace boost::corosio {
46 :
47 : /** Sends and receives datagrams over a Unix domain socket, from a coroutine.
48 :
49 : This class provides asynchronous Unix domain datagram socket
50 : operations that return awaitable types. Each operation
51 : participates in the affine awaitable protocol, ensuring
52 : coroutines resume on the correct executor.
53 :
54 : Supports two modes of operation:
55 :
56 : @li **Connectionless:** each send_to() specifies a destination
57 : endpoint, and each recv_from() captures the source. The
58 : socket must be opened (and optionally bound) before I/O.
59 :
60 : @li **Connected:** call connect() to set a default peer,
61 : then use send()/recv() without endpoint arguments. The
62 : kernel filters incoming datagrams to those from the
63 : connected peer.
64 :
65 : @note Not available on Windows. Windows does not support
66 : AF_UNIX datagram sockets (SOCK_DGRAM). Attempting to
67 : open this socket on Windows fails.
68 :
69 : @par Cancellation
70 : All asynchronous operations support cancellation through
71 : `std::stop_token` via the affine protocol, or explicitly
72 : through cancel(). Cancelled operations complete with
73 : `capy::cond::canceled`. Datagram sends and receives are
74 : atomic — there is no partial progress on cancellation.
75 :
76 : @par Thread Safety
77 : Distinct objects: Safe.@n
78 : Shared objects: Unsafe. A socket must not have concurrent
79 : operations of the same type (e.g., two simultaneous
80 : `recv_from`). One send and one `recv` may be in flight
81 : simultaneously. Both `recv` and `recv_from` share the
82 : same internal read slot, so they must not overlap. Likewise,
83 : send and `send_to` share the write slot.
84 :
85 : @par Example
86 : @par !example connectionless_and_connected
87 : */
88 : class BOOST_COROSIO_DECL local_datagram_socket : public io_object
89 : {
90 : public:
91 : /// The shutdown direction type used by shutdown().
92 : using shutdown_type = corosio::shutdown_type;
93 : using enum corosio::shutdown_type;
94 :
95 : /** Define backend hooks for local datagram socket operations.
96 :
97 : Platform backends (epoll, kqueue, select) derive from this
98 : to implement datagram I/O, connection, and option management.
99 : */
100 : struct implementation : io_object::implementation
101 : {
102 : /** Initiate an asynchronous `send_to` operation.
103 :
104 : @param cont Continuation to resume on completion; it lives in
105 : the awaiting frame until then.
106 : @param ex Executor for dispatching the completion.
107 : @param buf The buffer data to send.
108 : @param dest The destination endpoint.
109 : @param flags Message flags (e.g. `message_flags::do_not_route`).
110 : @param token Stop token for cancellation.
111 : @param ec Output error code.
112 : @param bytes_out Output bytes transferred.
113 :
114 : @return Coroutine handle to resume immediately.
115 : */
116 : virtual std::coroutine_handle<> send_to(
117 : capy::continuation& cont,
118 : capy::executor_ref ex,
119 : detail::buffer_param buf,
120 : corosio::local_endpoint dest,
121 : int flags,
122 : std::stop_token token,
123 : std::error_code* ec,
124 : std::size_t* bytes_out) = 0;
125 :
126 : /** Initiate an asynchronous `recv_from` operation.
127 :
128 : @param cont Continuation to resume on completion; it lives in
129 : the awaiting frame until then.
130 : @param ex Executor for dispatching the completion.
131 : @param buf The buffer to receive into.
132 : @param source Output endpoint for the sender's address.
133 : @param flags Message flags (e.g. `message_flags::peek`).
134 : @param token Stop token for cancellation.
135 : @param ec Output error code.
136 : @param bytes_out Output bytes transferred.
137 :
138 : @return Coroutine handle to resume immediately.
139 : */
140 : virtual std::coroutine_handle<> recv_from(
141 : capy::continuation& cont,
142 : capy::executor_ref ex,
143 : detail::buffer_param buf,
144 : corosio::local_endpoint* source,
145 : int flags,
146 : std::stop_token token,
147 : std::error_code* ec,
148 : std::size_t* bytes_out) = 0;
149 :
150 : /** Initiate an asynchronous connect to set the default peer.
151 :
152 : @param cont Continuation to resume on completion; it lives in
153 : the awaiting frame until then.
154 : @param ex Executor for dispatching the completion.
155 : @param ep The remote endpoint to connect to.
156 : @param token Stop token for cancellation.
157 : @param ec Output error code.
158 :
159 : @return Coroutine handle to resume immediately.
160 : */
161 : virtual std::coroutine_handle<> connect(
162 : capy::continuation& cont,
163 : capy::executor_ref ex,
164 : corosio::local_endpoint ep,
165 : std::stop_token token,
166 : std::error_code* ec) = 0;
167 :
168 : /** Initiate an asynchronous connected send operation.
169 :
170 : @param cont Continuation to resume on completion; it lives in
171 : the awaiting frame until then.
172 : @param ex Executor for dispatching the completion.
173 : @param buf The buffer data to send.
174 : @param flags Message flags (e.g. `message_flags::do_not_route`).
175 : @param token Stop token for cancellation.
176 : @param ec Output error code.
177 : @param bytes_out Output bytes transferred.
178 :
179 : @return Coroutine handle to resume immediately.
180 : */
181 : virtual std::coroutine_handle<> send(
182 : capy::continuation& cont,
183 : capy::executor_ref ex,
184 : detail::buffer_param buf,
185 : int flags,
186 : std::stop_token token,
187 : std::error_code* ec,
188 : std::size_t* bytes_out) = 0;
189 :
190 : /** Initiate an asynchronous connected `recv` operation.
191 :
192 : @param cont Continuation to resume on completion; it lives in
193 : the awaiting frame until then.
194 : @param ex Executor for dispatching the completion.
195 : @param buf The buffer to receive into.
196 : @param flags Message flags (e.g. `message_flags::peek`).
197 : @param token Stop token for cancellation.
198 : @param ec Output error code.
199 : @param bytes_out Output bytes transferred.
200 :
201 : @return Coroutine handle to resume immediately.
202 : */
203 : virtual std::coroutine_handle<> recv(
204 : capy::continuation& cont,
205 : capy::executor_ref ex,
206 : detail::buffer_param buf,
207 : int flags,
208 : std::stop_token token,
209 : std::error_code* ec,
210 : std::size_t* bytes_out) = 0;
211 :
212 : /** Initiate an asynchronous wait for socket readiness.
213 :
214 : Completes when the socket becomes ready for the
215 : specified direction, or an error condition is
216 : reported. No bytes are transferred.
217 :
218 : @param cont Continuation to resume on completion; it lives in
219 : the awaiting frame until then.
220 : @param ex Executor for dispatching the completion.
221 : @param w The direction to wait on.
222 : @param token Stop token for cancellation.
223 : @param ec Output error code.
224 :
225 : @return Coroutine handle to resume immediately.
226 : */
227 : virtual std::coroutine_handle<> wait(
228 : capy::continuation& cont,
229 : capy::executor_ref ex,
230 : wait_type w,
231 : std::stop_token token,
232 : std::error_code* ec) = 0;
233 :
234 : /** Shut down part or all of the socket.
235 :
236 : @param what Which directions to disable.
237 :
238 : @return The error code, empty on success.
239 : */
240 : virtual std::error_code shutdown(shutdown_type what) noexcept = 0;
241 :
242 : /// Return the platform socket descriptor.
243 : virtual native_handle_type native_handle() const noexcept = 0;
244 :
245 : /** Return the socket's address family.
246 :
247 : Local sockets have no IP family; implementations return
248 : `v4`, which the family-neutral options applicable to them
249 : ignore.
250 :
251 : @return The address family for option rendering.
252 : */
253 : virtual corosio::family family() const noexcept = 0;
254 :
255 : /** Release ownership of the socket descriptor.
256 :
257 : The implementation deregisters from the reactor and cancels
258 : pending operations. The caller takes ownership of the
259 : returned descriptor.
260 :
261 : @return The native handle, or an invalid sentinel if
262 : not open.
263 : */
264 : virtual native_handle_type release_socket() noexcept = 0;
265 :
266 : /** Request cancellation of pending asynchronous operations.
267 :
268 : Operations still in flight complete with `operation_canceled`;
269 : an operation whose result is already decided reports that
270 : result. Check `ec == cond::canceled` for portable comparison.
271 : */
272 : virtual void cancel() noexcept = 0;
273 :
274 : /** Set a socket option.
275 :
276 : @param level The protocol level (e.g. SOL_SOCKET).
277 : @param optname The option name.
278 : @param data Pointer to the option value.
279 : @param size Size of the option value in bytes.
280 : @return Error code on failure, empty on success.
281 : */
282 : virtual std::error_code set_option(
283 : int level,
284 : int optname,
285 : void const* data,
286 : std::size_t size) noexcept = 0;
287 :
288 : /** Get a socket option.
289 :
290 : @param level The protocol level (e.g. SOL_SOCKET).
291 : @param optname The option name.
292 : @param data Pointer to receive the option value.
293 : @param size On entry, the size of the buffer. On exit,
294 : the size of the option value.
295 : @return Error code on failure, empty on success.
296 : */
297 : virtual std::error_code
298 : get_option(int level, int optname, void* data, std::size_t* size)
299 : const noexcept = 0;
300 :
301 : /// Return the cached local endpoint.
302 : virtual corosio::local_endpoint local_endpoint() const noexcept = 0;
303 :
304 : /// Return the cached remote endpoint (connected mode).
305 : virtual corosio::local_endpoint remote_endpoint() const noexcept = 0;
306 :
307 : /** Bind the socket to a local endpoint.
308 :
309 : @param ep The local endpoint to bind to.
310 : @return Error code on failure, empty on success.
311 : */
312 : virtual std::error_code bind(corosio::local_endpoint ep) noexcept = 0;
313 : };
314 :
315 : /** Represent the awaitable returned by @ref send_to.
316 :
317 : Captures the destination endpoint and buffer, then dispatches
318 : to the backend implementation on suspension.
319 : */
320 : struct send_to_awaitable : detail::bytes_op_base<send_to_awaitable>
321 : {
322 : private:
323 : friend local_datagram_socket;
324 :
325 HIT 88 : send_to_awaitable(
326 : local_datagram_socket& s,
327 : detail::buffer_param buf,
328 : corosio::local_endpoint dest,
329 : int flags = 0) noexcept
330 176 : : s_(s)
331 88 : , buf_(buf)
332 88 : , dest_(dest)
333 88 : , flags_(flags)
334 : {
335 88 : }
336 :
337 : friend detail::bytes_op_base<send_to_awaitable>;
338 :
339 : local_datagram_socket& s_;
340 : detail::buffer_param buf_;
341 : corosio::local_endpoint dest_;
342 : int flags_;
343 :
344 : std::coroutine_handle<>
345 84 : dispatch(capy::continuation& cont, capy::executor_ref ex) const
346 : {
347 168 : return s_.get().send_to(
348 168 : cont, ex, buf_, dest_, flags_, token_, &ec_, &bytes_);
349 : }
350 : };
351 :
352 : /** Represent the awaitable returned by @ref recv_from.
353 :
354 : Captures the source endpoint reference and buffer, then
355 : dispatches to the backend implementation on suspension.
356 : */
357 : struct recv_from_awaitable : detail::bytes_op_base<recv_from_awaitable>
358 : {
359 : private:
360 : friend local_datagram_socket;
361 :
362 88 : recv_from_awaitable(
363 : local_datagram_socket& s,
364 : detail::buffer_param buf,
365 : corosio::local_endpoint& source,
366 : int flags = 0) noexcept
367 176 : : s_(s)
368 88 : , buf_(buf)
369 88 : , source_(source)
370 88 : , flags_(flags)
371 : {
372 88 : }
373 :
374 : friend detail::bytes_op_base<recv_from_awaitable>;
375 :
376 : local_datagram_socket& s_;
377 : detail::buffer_param buf_;
378 : corosio::local_endpoint& source_;
379 : int flags_;
380 :
381 : std::coroutine_handle<>
382 84 : dispatch(capy::continuation& cont, capy::executor_ref ex) const
383 : {
384 168 : return s_.get().recv_from(
385 168 : cont, ex, buf_, &source_, flags_, token_, &ec_, &bytes_);
386 : }
387 : };
388 :
389 : /** Represent the awaitable returned by @ref connect.
390 :
391 : Captures the target endpoint, then dispatches to the
392 : backend implementation on suspension.
393 : */
394 : struct connect_awaitable : detail::void_op_base<connect_awaitable>
395 : {
396 : private:
397 : friend local_datagram_socket;
398 :
399 2 : connect_awaitable(
400 : local_datagram_socket& s, corosio::local_endpoint ep) noexcept
401 4 : : s_(s)
402 2 : , endpoint_(ep)
403 : {
404 2 : }
405 :
406 : friend detail::void_op_base<connect_awaitable>;
407 :
408 : local_datagram_socket& s_;
409 : corosio::local_endpoint endpoint_;
410 :
411 : std::coroutine_handle<>
412 2 : dispatch(capy::continuation& cont, capy::executor_ref ex) const
413 : {
414 2 : return s_.get().connect(cont, ex, endpoint_, token_, &ec_);
415 : }
416 : };
417 :
418 : /// Represent the awaitable returned by @ref wait.
419 : struct wait_awaitable : detail::void_op_base<wait_awaitable>
420 : {
421 : private:
422 : friend local_datagram_socket;
423 :
424 14 : wait_awaitable(local_datagram_socket& s, wait_type w) noexcept
425 28 : : s_(s)
426 14 : , w_(w)
427 : {
428 14 : }
429 :
430 : friend detail::void_op_base<wait_awaitable>;
431 :
432 : local_datagram_socket& s_;
433 : wait_type w_;
434 :
435 : std::coroutine_handle<>
436 12 : dispatch(capy::continuation& cont, capy::executor_ref ex) const
437 : {
438 12 : return s_.get().wait(cont, ex, w_, token_, &ec_);
439 : }
440 : };
441 :
442 : /** Represent the awaitable returned by @ref send.
443 :
444 : Captures the buffer, then dispatches to the backend
445 : implementation on suspension. Requires a prior connect().
446 : */
447 : struct send_awaitable : detail::bytes_op_base<send_awaitable>
448 : {
449 : private:
450 : friend local_datagram_socket;
451 :
452 97 : send_awaitable(
453 : local_datagram_socket& s,
454 : detail::buffer_param buf,
455 : int flags = 0) noexcept
456 194 : : s_(s)
457 97 : , buf_(buf)
458 97 : , flags_(flags)
459 : {
460 97 : }
461 :
462 : friend detail::bytes_op_base<send_awaitable>;
463 :
464 : local_datagram_socket& s_;
465 : detail::buffer_param buf_;
466 : int flags_;
467 :
468 : std::coroutine_handle<>
469 93 : dispatch(capy::continuation& cont, capy::executor_ref ex) const
470 : {
471 93 : return s_.get().send(cont, ex, buf_, flags_, token_, &ec_, &bytes_);
472 : }
473 : };
474 :
475 : /** Represent the awaitable returned by @ref recv.
476 :
477 : Captures the buffer, then dispatches to the backend
478 : implementation on suspension. Requires a prior connect().
479 : */
480 : struct recv_awaitable : detail::bytes_op_base<recv_awaitable>
481 : {
482 : private:
483 : friend local_datagram_socket;
484 :
485 97 : recv_awaitable(
486 : local_datagram_socket& s,
487 : detail::buffer_param buf,
488 : int flags = 0) noexcept
489 194 : : s_(s)
490 97 : , buf_(buf)
491 97 : , flags_(flags)
492 : {
493 97 : }
494 :
495 : friend detail::bytes_op_base<recv_awaitable>;
496 :
497 : local_datagram_socket& s_;
498 : detail::buffer_param buf_;
499 : int flags_;
500 :
501 : std::coroutine_handle<>
502 93 : dispatch(capy::continuation& cont, capy::executor_ref ex) const
503 : {
504 93 : return s_.get().recv(cont, ex, buf_, flags_, token_, &ec_, &bytes_);
505 : }
506 : };
507 :
508 : public:
509 : /** Destructor.
510 :
511 : Closes the socket if open, cancelling any pending operations.
512 : */
513 : ~local_datagram_socket() override;
514 :
515 : /** Construct a socket from an execution context.
516 :
517 : @param ctx The execution context that owns this socket.
518 : */
519 : explicit local_datagram_socket(capy::execution_context& ctx);
520 :
521 : /** Construct a socket from an executor.
522 :
523 : The socket is associated with the executor's context.
524 :
525 : @tparam Ex A type satisfying capy::Executor.
526 :
527 : @param ex The executor whose context owns the socket.
528 : */
529 : template<class Ex>
530 : requires(!std::
531 : same_as<std::remove_cvref_t<Ex>, local_datagram_socket>) &&
532 : capy::Executor<Ex>
533 : explicit local_datagram_socket(Ex const& ex)
534 : : local_datagram_socket(ex.context())
535 : {
536 : }
537 :
538 : /** Move constructor.
539 :
540 : Transfers ownership of the socket resources.
541 :
542 : @param other The socket to move from.
543 : */
544 2 : local_datagram_socket(local_datagram_socket&& other) noexcept
545 2 : : io_object(std::move(other))
546 : {
547 2 : }
548 :
549 : /** Move assignment operator.
550 :
551 : Closes any existing socket and transfers ownership.
552 :
553 : @param other The socket to move from.
554 : @return Reference to this socket.
555 : */
556 2 : local_datagram_socket& operator=(local_datagram_socket&& other) noexcept
557 : {
558 2 : if (this != &other)
559 : {
560 2 : close();
561 2 : io_object::operator=(std::move(other));
562 : }
563 2 : return *this;
564 : }
565 :
566 : /// Copy construction is disabled; the handle is uniquely owned.
567 : local_datagram_socket(local_datagram_socket const&) = delete;
568 : /// Copy assignment is disabled; the handle is uniquely owned.
569 : local_datagram_socket& operator=(local_datagram_socket const&) = delete;
570 :
571 : /** Open the socket.
572 :
573 : Creates a Unix datagram socket and associates it with
574 : the platform reactor.
575 :
576 : Failures such as descriptor exhaustion are normal runtime
577 : conditions and are reported through the returned error code.
578 : Opening an already-open socket is a no-op that reports
579 : success.
580 :
581 :
582 : @return The error code, empty on success.
583 : */
584 : [[nodiscard]] std::error_code open() noexcept;
585 :
586 : /** Close the socket.
587 :
588 : Cancels any pending asynchronous operations and releases
589 : the underlying file descriptor. Has no effect if the
590 : socket is not open.
591 :
592 : @post is_open() == false
593 : */
594 : void close() noexcept;
595 :
596 : /** Check if the socket is open.
597 :
598 : @return `true` if the socket holds a valid file descriptor,
599 : `false` otherwise.
600 : */
601 1401 : bool is_open() const noexcept
602 : {
603 : #if BOOST_COROSIO_HAS_IOCP && !defined(BOOST_COROSIO_MRDOCS)
604 : return h_ && get().native_handle() != ~native_handle_type(0);
605 : #else
606 1401 : return h_ && get().native_handle() >= 0;
607 : #endif
608 : }
609 :
610 : /** Bind the socket to a local endpoint.
611 :
612 : Associates the socket with a local address (filesystem path).
613 : Required before calling `recv_from` in connectionless mode.
614 :
615 : @param ep The local endpoint to bind to.
616 :
617 : @return Error code on failure, empty on success.
618 :
619 : A closed socket reports `errc::bad_file_descriptor`.
620 : */
621 : [[nodiscard]] std::error_code bind(corosio::local_endpoint ep) noexcept;
622 :
623 : /** Initiate an asynchronous connect to set the default peer.
624 :
625 : If the socket is not already open, it is opened automatically.
626 : After successful completion, send()/recv() may be used
627 : without specifying an endpoint.
628 :
629 : @param ep The remote endpoint to connect to.
630 :
631 : @par Cancellation
632 : Supports cancellation via the awaitable's stop_token or by
633 : calling cancel(). On cancellation, yields
634 : `capy::cond::canceled`.
635 :
636 : @return An awaitable that completes with `results<>`.
637 :
638 : If the socket needs to be opened and the open fails, the
639 : awaitable completes immediately with that error.
640 : */
641 2 : [[nodiscard]] auto connect(corosio::local_endpoint ep)
642 : {
643 2 : connect_awaitable aw(*this, ep);
644 2 : if (!is_open())
645 2 : aw.ec_ = open();
646 2 : return aw;
647 : }
648 :
649 : /** Wait for the socket to become ready in a given direction.
650 :
651 : Suspends until the socket is ready for the requested
652 : direction, or an error condition is reported. No bytes
653 : are transferred.
654 :
655 : @param w The wait direction (read, write, or error).
656 :
657 : @return An awaitable that completes with `results<>`.
658 :
659 : A closed socket completes with `errc::bad_file_descriptor`.
660 :
661 : @pre This socket must outlive the returned awaitable.
662 : */
663 14 : [[nodiscard]] auto wait(wait_type w)
664 : {
665 14 : return wait_awaitable(*this, w);
666 : }
667 :
668 : /** Send a datagram to the specified destination.
669 :
670 : Completes when the transport accepts the entire datagram
671 : by the kernel. The `bytes_transferred` value equals the
672 : datagram size on success.
673 :
674 : @param buf The buffer containing data to send.
675 : @param dest The destination endpoint.
676 : @param flags Message flags (e.g. message_flags::do_not_route).
677 :
678 : @par Cancellation
679 : Supports cancellation via stop_token or cancel().
680 :
681 : @return An awaitable that completes with
682 : results<std::size_t>.
683 :
684 : A closed socket reports `errc::bad_file_descriptor`.
685 : */
686 : template<capy::ConstBufferSequence Buffers>
687 88 : [[nodiscard]] auto send_to(
688 : Buffers const& buf,
689 : corosio::local_endpoint dest,
690 : corosio::message_flags flags)
691 : {
692 88 : send_to_awaitable aw(*this, buf, dest, static_cast<int>(flags));
693 88 : if (!is_open())
694 2 : aw.ec_ = make_error_code(std::errc::bad_file_descriptor);
695 88 : return aw;
696 : }
697 :
698 : /// @overload
699 : template<capy::ConstBufferSequence Buffers>
700 88 : [[nodiscard]] auto send_to(Buffers const& buf, corosio::local_endpoint dest)
701 : {
702 88 : return send_to(buf, dest, corosio::message_flags::none);
703 : }
704 :
705 : /** Receive a datagram and capture the sender's endpoint.
706 :
707 : Completes when one datagram arrives. The
708 : `bytes_transferred` value is the number of bytes copied
709 : into the buffer. If the buffer is smaller than the
710 : datagram, excess bytes are discarded (datagram
711 : semantics).
712 :
713 : @param buf The buffer to receive data into.
714 : @param source Reference to an endpoint that receives
715 : the sender's address on successful completion.
716 : @param flags Message flags (e.g. message_flags::peek).
717 :
718 : @par Cancellation
719 : Supports cancellation via stop_token or cancel().
720 :
721 : @return An awaitable that completes with
722 : results<std::size_t>.
723 :
724 : A closed socket reports `errc::bad_file_descriptor`.
725 : */
726 : template<capy::MutableBufferSequence Buffers>
727 88 : [[nodiscard]] auto recv_from(
728 : Buffers const& buf,
729 : corosio::local_endpoint& source,
730 : corosio::message_flags flags)
731 : {
732 88 : recv_from_awaitable aw(*this, buf, source, static_cast<int>(flags));
733 88 : if (!is_open())
734 2 : aw.ec_ = make_error_code(std::errc::bad_file_descriptor);
735 88 : return aw;
736 : }
737 :
738 : /// @overload
739 : template<capy::MutableBufferSequence Buffers>
740 : [[nodiscard]] auto
741 86 : recv_from(Buffers const& buf, corosio::local_endpoint& source)
742 : {
743 86 : return recv_from(buf, source, corosio::message_flags::none);
744 : }
745 :
746 : /** Send a datagram to the connected peer.
747 :
748 : @pre connect() succeeded.
749 :
750 : @param buf The buffer containing data to send.
751 : @param flags Message flags.
752 :
753 : @par Cancellation
754 : Supports cancellation via stop_token or cancel().
755 :
756 : @return An awaitable that completes with
757 : results<std::size_t>.
758 :
759 : A closed socket reports `errc::bad_file_descriptor`.
760 : */
761 : template<capy::ConstBufferSequence Buffers>
762 97 : [[nodiscard]] auto send(Buffers const& buf, corosio::message_flags flags)
763 : {
764 97 : send_awaitable aw(*this, buf, static_cast<int>(flags));
765 97 : if (!is_open())
766 2 : aw.ec_ = make_error_code(std::errc::bad_file_descriptor);
767 97 : return aw;
768 : }
769 :
770 : /// @overload
771 : template<capy::ConstBufferSequence Buffers>
772 97 : [[nodiscard]] auto send(Buffers const& buf)
773 : {
774 97 : return send(buf, corosio::message_flags::none);
775 : }
776 :
777 : /** Receive a datagram from the connected peer.
778 :
779 : @pre connect() succeeded.
780 :
781 : @param buf The buffer to receive data into.
782 : @param flags Message flags (e.g. message_flags::peek).
783 :
784 : @par Cancellation
785 : Supports cancellation via stop_token or cancel().
786 :
787 : @return An awaitable that completes with
788 : results<std::size_t>.
789 :
790 : A closed socket reports `errc::bad_file_descriptor`.
791 : */
792 : template<capy::MutableBufferSequence Buffers>
793 97 : [[nodiscard]] auto recv(Buffers const& buf, corosio::message_flags flags)
794 : {
795 97 : recv_awaitable aw(*this, buf, static_cast<int>(flags));
796 97 : if (!is_open())
797 2 : aw.ec_ = make_error_code(std::errc::bad_file_descriptor);
798 97 : return aw;
799 : }
800 :
801 : /// @overload
802 : template<capy::MutableBufferSequence Buffers>
803 95 : [[nodiscard]] auto recv(Buffers const& buf)
804 : {
805 95 : return recv(buf, corosio::message_flags::none);
806 : }
807 :
808 : /** Cancel any pending asynchronous operations.
809 :
810 : Operations still in flight complete with
811 : `errc::operation_canceled`; an operation whose result is
812 : already decided reports that result. Check
813 : `ec == cond::canceled` for portable comparison.
814 : */
815 : void cancel() noexcept;
816 :
817 : /** Get the native socket handle.
818 :
819 : @return The native socket handle, or -1 if not open.
820 : */
821 : native_handle_type native_handle() const noexcept;
822 :
823 : /** Release ownership of the native socket handle.
824 :
825 : Deregisters the socket from the reactor and cancels pending
826 : operations without closing the fd. The caller takes ownership
827 : of the returned descriptor.
828 :
829 : A closed object reports `errc::bad_file_descriptor` and the
830 : returned handle is the invalid sentinel ( -1 ), never zero.
831 :
832 : @return The error code and the native handle.
833 : */
834 : [[nodiscard]] capy::results<native_handle_type> release() noexcept;
835 :
836 : /** Query the number of bytes available for reading.
837 :
838 : A closed socket reports `errc::bad_file_descriptor`. Other
839 : failures carry the error code from the operating system. On
840 : failure the count is zero.
841 :
842 : @return The error code and the number of readable bytes.
843 : */
844 : [[nodiscard]] capy::results<std::size_t> available() const noexcept;
845 :
846 : /** Shut down part or all of the socket.
847 :
848 : Failures such as an unconnected socket are normal runtime
849 : conditions and are reported through the returned error
850 : code. A closed socket reports `errc::bad_file_descriptor`.
851 :
852 : @param what Which direction to shut down.
853 :
854 : @return The error code, empty on success.
855 : */
856 : [[nodiscard]] std::error_code shutdown(shutdown_type what) noexcept;
857 :
858 : /** Set a socket option.
859 :
860 : Fails with `errc::bad_file_descriptor` if the socket is not
861 : open, or with the error the operating system reports.
862 :
863 : @tparam Option A socket option type that provides static
864 : `level()` and `name()` members, and `data()` / `size()`
865 : accessors for the option value.
866 :
867 : @param opt The option to set.
868 :
869 : @return The error code, empty on success.
870 : */
871 : template<class Option>
872 24 : [[nodiscard]] std::error_code set_option(Option const& opt) noexcept
873 : {
874 24 : if (!is_open())
875 2 : return make_error_code(std::errc::bad_file_descriptor);
876 22 : auto const fam = get().family();
877 22 : return get().set_option(
878 22 : opt.level(fam), opt.name(fam), opt.data(fam), opt.size(fam));
879 : }
880 :
881 : /** Get a socket option.
882 :
883 : Fails with `errc::bad_file_descriptor` if the socket is not
884 : open, or with the error the operating system reports. On
885 : failure the option is value-initialized.
886 :
887 : @tparam Option A socket option type that provides static
888 : `level()` and `name()` members, `data()` / `size()`
889 : accessors, and a `resize()` member.
890 :
891 : @return The error code and the option value.
892 : */
893 : template<class Option>
894 8 : [[nodiscard]] capy::results<Option> get_option() const noexcept
895 : {
896 8 : if (!is_open())
897 2 : return {make_error_code(std::errc::bad_file_descriptor), Option{}};
898 6 : Option opt{};
899 6 : auto const fam = get().family();
900 6 : std::size_t sz = opt.size(fam);
901 6 : if (auto ec = get().get_option(
902 : opt.level(fam), opt.name(fam), opt.data(fam), &sz))
903 2 : return {ec, Option{}};
904 4 : opt.resize(fam, sz);
905 4 : return {std::error_code{}, std::move(opt)};
906 : }
907 :
908 : /** Assign an existing native socket to this object.
909 :
910 : Adopts a Unix domain datagram socket created outside the
911 : library — from `socketpair()`, received over `SCM_RIGHTS`,
912 : or made natively — and registers it with the backend. The
913 : socket must be a datagram socket in the `AF_UNIX` family.
914 : Adoption never alters the descriptor's flags or options.
915 : The fd must already be non-blocking.
916 :
917 : The object must be closed. To replace a held socket, `close()`
918 : or `release()` it first.
919 :
920 : @par Exception Safety
921 : Throws nothing. On failure the object is unchanged and the
922 : caller retains ownership of `fd`.
923 :
924 : @param fd The native socket to adopt. On success the object
925 : owns it and closes it.
926 :
927 : @return `error::already_open` if this object is open.
928 : Otherwise the error code, empty on success. Validation and
929 : registration failures are normal runtime conditions when
930 : adopting foreign descriptors.
931 : */
932 : [[nodiscard]] std::error_code assign(native_handle_type fd) noexcept;
933 :
934 : /** Get the local endpoint of the socket.
935 :
936 : @return The local endpoint, or a default endpoint if not bound.
937 : */
938 : corosio::local_endpoint local_endpoint() const noexcept;
939 :
940 : /** Get the remote endpoint of the socket.
941 :
942 : Returns the address of the connected peer.
943 :
944 : @return The remote endpoint, or a default endpoint if
945 : not connected.
946 : */
947 : corosio::local_endpoint remote_endpoint() const noexcept;
948 :
949 : protected:
950 : /// Default-construct (for derived types).
951 : local_datagram_socket() noexcept = default;
952 :
953 : /// Construct from a pre-built handle.
954 30 : explicit local_datagram_socket(handle h) noexcept : io_object(std::move(h))
955 : {
956 30 : }
957 :
958 : private:
959 : [[nodiscard]] std::error_code
960 : open_for_family(int family, int type, int protocol) noexcept;
961 :
962 1858 : inline implementation& get() const noexcept
963 : {
964 1858 : return *static_cast<implementation*>(h_.get());
965 : }
966 : };
967 :
968 : } // namespace boost::corosio
969 :
970 : #endif // BOOST_COROSIO_POSIX
971 :
972 : #endif // BOOST_COROSIO_LOCAL_DATAGRAM_SOCKET_HPP
|
