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_STREAM_SOCKET_HPP
11 : #define BOOST_COROSIO_LOCAL_STREAM_SOCKET_HPP
12 :
13 : #include <boost/corosio/family.hpp>
14 : #include <boost/corosio/detail/config.hpp>
15 : #include <boost/corosio/detail/platform.hpp>
16 : #include <boost/corosio/detail/except.hpp>
17 : #include <boost/corosio/detail/native_handle.hpp>
18 : #include <boost/corosio/detail/op_base.hpp>
19 : #include <boost/corosio/io/io_stream.hpp>
20 : #include <boost/capy/io_result.hpp>
21 : #include <boost/corosio/detail/buffer_param.hpp>
22 : #include <boost/corosio/local_endpoint.hpp>
23 : #include <boost/corosio/shutdown_type.hpp>
24 : #include <boost/corosio/wait_type.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 : /** Reads and writes a Unix domain stream, from a coroutine.
41 :
42 : This class provides asynchronous Unix domain stream socket
43 : operations that return awaitable types. Each operation
44 : participates in the affine awaitable protocol, ensuring
45 : coroutines resume on the correct executor.
46 :
47 : The socket must be opened before performing I/O operations.
48 : Operations support cancellation through `std::stop_token` via
49 : the affine protocol, or explicitly through the `cancel()`
50 : member function.
51 :
52 : @par Thread Safety
53 : Distinct objects: Safe.@n
54 : Shared objects: Unsafe. A socket must not have concurrent
55 : operations of the same type (e.g., two simultaneous reads).
56 : One read and one write may be in flight simultaneously.
57 :
58 : @par Semantics
59 : Wraps the platform Unix domain socket stack. Operations
60 : dispatch to OS socket APIs via the `io_context` backend
61 : (epoll, kqueue, select, or IOCP). Satisfies @ref capy::Stream.
62 :
63 : @par Example
64 : @par !example connect_and_read
65 : */
66 : class BOOST_COROSIO_DECL local_stream_socket : public io_stream
67 : {
68 : public:
69 : /// The endpoint type used by this socket.
70 : using endpoint_type = corosio::local_endpoint;
71 :
72 : /// The shutdown direction type used by this socket.
73 : using shutdown_type = corosio::shutdown_type;
74 : using enum corosio::shutdown_type;
75 :
76 : /** Define backend hooks for local stream socket operations.
77 :
78 : Platform backends (epoll, kqueue, select) derive from this
79 : to implement socket I/O, connection, and option management.
80 : */
81 : struct implementation : io_stream::implementation
82 : {
83 : /** Initiate an asynchronous connect to the given endpoint.
84 :
85 : @param h Coroutine handle to resume on completion.
86 : @param ex Executor for dispatching the completion.
87 : @param ep The local endpoint (path) to connect to.
88 : @param token Stop token for cancellation.
89 : @param ec Output error code.
90 :
91 : @return Coroutine handle to resume immediately.
92 : */
93 : virtual std::coroutine_handle<> connect(
94 : std::coroutine_handle<> h,
95 : capy::executor_ref ex,
96 : corosio::local_endpoint ep,
97 : std::stop_token token,
98 : std::error_code* ec) = 0;
99 :
100 : /** Initiate an asynchronous wait for socket readiness.
101 :
102 : Completes when the socket becomes ready for the
103 : specified direction, or an error condition is
104 : reported. No bytes are transferred.
105 :
106 : @param h Coroutine handle to resume on completion.
107 : @param ex Executor for dispatching the completion.
108 : @param w The direction to wait on.
109 : @param token Stop token for cancellation.
110 : @param ec Output error code.
111 :
112 : @return Coroutine handle to resume immediately.
113 : */
114 : virtual std::coroutine_handle<> wait(
115 : std::coroutine_handle<> h,
116 : capy::executor_ref ex,
117 : wait_type w,
118 : std::stop_token token,
119 : std::error_code* ec) = 0;
120 :
121 : /** Shut down the socket for the given direction(s).
122 :
123 : @param what The shutdown direction.
124 :
125 : @return Error code on failure, empty on success.
126 : */
127 : virtual std::error_code shutdown(shutdown_type what) noexcept = 0;
128 :
129 : /// Return the platform socket descriptor.
130 : virtual native_handle_type native_handle() const noexcept = 0;
131 :
132 : /** Return the socket's address family.
133 :
134 : Local sockets have no IP family; implementations return
135 : `v4`, which the family-neutral options applicable to them
136 : ignore.
137 :
138 : @return The address family for option rendering.
139 : */
140 : virtual corosio::family family() const noexcept = 0;
141 :
142 : /** Release ownership of the native socket handle.
143 :
144 : Deregisters the socket from the reactor without closing
145 : the descriptor. The caller takes ownership.
146 :
147 : @return The native handle.
148 : */
149 : virtual native_handle_type release_socket() noexcept = 0;
150 :
151 : /** Request cancellation of pending asynchronous operations.
152 :
153 : Operations still in flight complete with `operation_canceled`; an
154 : operation whose result is already decided reports that result.
155 : Check `ec == cond::canceled` for portable comparison.
156 : */
157 : virtual void cancel() noexcept = 0;
158 :
159 : /** Set a socket option.
160 :
161 : @param level The protocol level (e.g. `SOL_SOCKET`).
162 : @param optname The option name (e.g. `SO_KEEPALIVE`).
163 : @param data Pointer to the option value.
164 : @param size Size of the option value in bytes.
165 : @return Error code on failure, empty on success.
166 : */
167 : virtual std::error_code set_option(
168 : int level,
169 : int optname,
170 : void const* data,
171 : std::size_t size) noexcept = 0;
172 :
173 : /** Get a socket option.
174 :
175 : @param level The protocol level (e.g. `SOL_SOCKET`).
176 : @param optname The option name (e.g. `SO_KEEPALIVE`).
177 : @param data Pointer to receive the option value.
178 : @param size On entry, the size of the buffer. On exit,
179 : the size of the option value.
180 : @return Error code on failure, empty on success.
181 : */
182 : virtual std::error_code
183 : get_option(int level, int optname, void* data, std::size_t* size)
184 : const noexcept = 0;
185 :
186 : /// Return the cached local endpoint.
187 : virtual corosio::local_endpoint local_endpoint() const noexcept = 0;
188 :
189 : /// Return the cached remote endpoint.
190 : virtual corosio::local_endpoint remote_endpoint() const noexcept = 0;
191 : };
192 :
193 : /// Represent the awaitable returned by @ref connect.
194 : struct connect_awaitable : detail::void_op_base<connect_awaitable>
195 : {
196 : private:
197 : friend local_stream_socket;
198 :
199 HIT 25 : connect_awaitable(
200 : local_stream_socket& s, corosio::local_endpoint ep) noexcept
201 50 : : s_(s)
202 25 : , endpoint_(ep)
203 : {
204 25 : }
205 :
206 : friend detail::void_op_base<connect_awaitable>;
207 :
208 : local_stream_socket& s_;
209 : corosio::local_endpoint endpoint_;
210 :
211 : std::coroutine_handle<>
212 23 : dispatch(std::coroutine_handle<> h, capy::executor_ref ex) const
213 : {
214 23 : return s_.get().connect(h, ex, endpoint_, token_, &ec_);
215 : }
216 : };
217 :
218 : /// Represent the awaitable returned by @ref wait.
219 : struct wait_awaitable : detail::void_op_base<wait_awaitable>
220 : {
221 : private:
222 : friend local_stream_socket;
223 :
224 16 : wait_awaitable(local_stream_socket& s, wait_type w) noexcept
225 32 : : s_(s)
226 16 : , w_(w)
227 : {
228 16 : }
229 :
230 : friend detail::void_op_base<wait_awaitable>;
231 :
232 : local_stream_socket& s_;
233 : wait_type w_;
234 :
235 : std::coroutine_handle<>
236 14 : dispatch(std::coroutine_handle<> h, capy::executor_ref ex) const
237 : {
238 14 : return s_.get().wait(h, ex, w_, token_, &ec_);
239 : }
240 : };
241 :
242 : public:
243 : /** Destructor.
244 :
245 : Closes the socket if open, cancelling any pending operations.
246 : */
247 : ~local_stream_socket() override;
248 :
249 : /** Construct a socket from an execution context.
250 :
251 : @param ctx The execution context that owns this socket.
252 : */
253 : explicit local_stream_socket(capy::execution_context& ctx);
254 :
255 : /** Construct a socket from an executor.
256 :
257 : The socket is associated with the executor's context.
258 :
259 : @tparam Ex A type satisfying capy::Executor.
260 :
261 : @param ex The executor whose context owns the socket.
262 : */
263 : template<class Ex>
264 : requires(!std::same_as<std::remove_cvref_t<Ex>, local_stream_socket>) &&
265 : capy::Executor<Ex>
266 : explicit local_stream_socket(Ex const& ex)
267 : : local_stream_socket(ex.context())
268 : {
269 : }
270 :
271 : /** Move constructor.
272 :
273 : Transfers ownership of the socket resources.
274 :
275 : @param other The socket to move from.
276 :
277 : @pre No awaitables returned by @p other's methods exist.
278 : @pre The execution context associated with @p other must
279 : outlive this socket.
280 : */
281 14 : local_stream_socket(local_stream_socket&& other) noexcept
282 14 : : io_object(std::move(other))
283 : {
284 14 : }
285 :
286 : /** Move assignment operator.
287 :
288 : Closes any existing socket and transfers ownership.
289 :
290 : @param other The socket to move from.
291 :
292 : @pre No awaitables returned by either `*this` or @p other's
293 : methods exist.
294 : @pre The execution context associated with @p other must
295 : outlive this socket.
296 :
297 : @return Reference to this socket.
298 : */
299 4 : local_stream_socket& operator=(local_stream_socket&& other) noexcept
300 : {
301 4 : if (this != &other)
302 : {
303 2 : close();
304 2 : io_object::operator=(std::move(other));
305 : }
306 4 : return *this;
307 : }
308 :
309 : /// Copy construction is disabled; the handle is uniquely owned.
310 : local_stream_socket(local_stream_socket const&) = delete;
311 : /// Copy assignment is disabled; the handle is uniquely owned.
312 : local_stream_socket& operator=(local_stream_socket const&) = delete;
313 :
314 : /** Open the socket.
315 :
316 : Creates a Unix stream socket and associates it with
317 : the platform reactor.
318 :
319 : Failures such as descriptor exhaustion are normal runtime
320 : conditions and are reported through the returned error code.
321 : Opening an already-open socket is a no-op that reports
322 : success.
323 :
324 :
325 : @return The error code, empty on success.
326 : */
327 : [[nodiscard]] std::error_code open() noexcept;
328 :
329 : /** Close the socket.
330 :
331 : Releases socket resources. Any pending operations complete
332 : with `errc::operation_canceled`.
333 : */
334 : void close() noexcept;
335 :
336 : /** Check if the socket is open.
337 :
338 : @return `true` if the socket is open and ready for operations.
339 : */
340 871 : bool is_open() const noexcept
341 : {
342 : #if BOOST_COROSIO_HAS_IOCP && !defined(BOOST_COROSIO_MRDOCS)
343 : return h_ && get().native_handle() != ~native_handle_type(0);
344 : #else
345 871 : return h_ && get().native_handle() >= 0;
346 : #endif
347 : }
348 :
349 : /** Initiate an asynchronous connect operation.
350 :
351 : If the socket is not already open, it is opened automatically.
352 :
353 : @param ep The local endpoint (path) to connect to.
354 :
355 : @return An awaitable that completes with io_result<>.
356 :
357 : If the socket needs to be opened and the open fails, the
358 : awaitable completes immediately with that error.
359 : */
360 25 : [[nodiscard]] auto connect(corosio::local_endpoint ep)
361 : {
362 25 : connect_awaitable aw(*this, ep);
363 25 : if (!is_open())
364 17 : aw.ec_ = open();
365 25 : return aw;
366 : }
367 :
368 : /** Wait for the socket to become ready in a given direction.
369 :
370 : Suspends until the socket is ready for the requested
371 : direction, or an error condition is reported. No bytes
372 : are transferred.
373 :
374 : @param w The wait direction (read, write, or error).
375 :
376 : @return An awaitable that completes with `io_result<>`.
377 :
378 : A closed socket completes with `errc::bad_file_descriptor`.
379 :
380 : @pre This socket must outlive the returned awaitable.
381 : */
382 16 : [[nodiscard]] auto wait(wait_type w)
383 : {
384 16 : return wait_awaitable(*this, w);
385 : }
386 :
387 : /** Cancel any pending asynchronous operations.
388 :
389 : Operations still in flight complete with `errc::operation_canceled`;
390 : an operation whose result is already decided reports that result.
391 : Check `ec == cond::canceled` for portable comparison.
392 : */
393 : void cancel() noexcept;
394 :
395 : /** Get the native socket handle.
396 :
397 : Returns the underlying platform-specific socket descriptor.
398 : On POSIX systems this is an `int` file descriptor.
399 :
400 : @return The native socket handle, or an invalid sentinel
401 : if not open.
402 : */
403 : native_handle_type native_handle() const noexcept;
404 :
405 : /** Query the number of bytes available for reading.
406 :
407 : @return The number of bytes that can be read without blocking.
408 :
409 : @throws std::system_error `errc::bad_file_descriptor` if the
410 : socket is not open; otherwise thrown on ioctl failure.
411 : */
412 : std::size_t available() const;
413 :
414 : /** Release ownership of the native socket handle.
415 :
416 : Deregisters the socket from the backend and cancels pending
417 : operations without closing the descriptor. The caller takes
418 : ownership of the returned handle.
419 :
420 : @return The native handle.
421 :
422 : @throws std::system_error `errc::bad_file_descriptor` if the
423 : socket is not open.
424 :
425 : @post is_open() == false
426 : */
427 : native_handle_type release();
428 :
429 : /** Disable sends or receives on the socket.
430 :
431 : Unix stream connections are full-duplex: each direction
432 : (send and receive) operates independently. This function
433 : allows you to close one or both directions without
434 : destroying the socket.
435 :
436 : Failures such as a peer that already disconnected are
437 : normal runtime conditions and are reported through the
438 : returned error code. A closed socket reports
439 : `errc::bad_file_descriptor`.
440 :
441 : @param what Determines which operations are no longer
442 : allowed.
443 :
444 : @return The error code, empty on success.
445 : */
446 : [[nodiscard]] std::error_code shutdown(shutdown_type what) noexcept;
447 :
448 : /** Set a socket option.
449 :
450 : Applies a type-safe socket option to the underlying socket.
451 : The option type encodes the protocol level and option name.
452 :
453 : @param opt The option to set.
454 :
455 : @throws std::system_error `errc::bad_file_descriptor` if the
456 : socket is not open; otherwise thrown on failure.
457 : */
458 : template<class Option>
459 14 : void set_option(Option const& opt)
460 : {
461 14 : if (!is_open())
462 2 : detail::throw_system_error(
463 4 : make_error_code(std::errc::bad_file_descriptor),
464 : "local_stream_socket::set_option");
465 12 : auto const fam = get().family();
466 12 : std::error_code ec = get().set_option(
467 : opt.level(fam), opt.name(fam), opt.data(fam), opt.size(fam));
468 12 : if (ec)
469 2 : detail::throw_system_error(ec, "local_stream_socket::set_option");
470 10 : }
471 :
472 : /** Get a socket option.
473 :
474 : Retrieves the current value of a type-safe socket option.
475 :
476 : @return The current option value.
477 :
478 : @throws std::system_error `errc::bad_file_descriptor` if the
479 : socket is not open; otherwise thrown on failure.
480 : */
481 : template<class Option>
482 10 : Option get_option() const
483 : {
484 10 : if (!is_open())
485 2 : detail::throw_system_error(
486 4 : make_error_code(std::errc::bad_file_descriptor),
487 : "local_stream_socket::get_option");
488 8 : Option opt{};
489 8 : auto const fam = get().family();
490 8 : std::size_t sz = opt.size(fam);
491 : std::error_code ec =
492 8 : get().get_option(opt.level(fam), opt.name(fam), opt.data(fam), &sz);
493 8 : if (ec)
494 2 : detail::throw_system_error(ec, "local_stream_socket::get_option");
495 6 : opt.resize(fam, sz);
496 6 : return opt;
497 : }
498 :
499 : /** Assign an existing native socket to this object.
500 :
501 : Adopts a Unix domain stream socket created outside the
502 : library — from `socketpair()`, received over `SCM_RIGHTS`,
503 : or made natively — and registers it with the backend. The
504 : socket must be a stream socket in the `AF_UNIX` family.
505 : Adoption never alters the descriptor's flags or options: on
506 : POSIX the fd must already be non-blocking, and on Windows
507 : the socket must be overlapped-capable.
508 :
509 : If this object is already open, pending operations complete
510 : with `errc::operation_canceled` and the held socket is
511 : closed before the new one is adopted.
512 :
513 : @par Exception Safety
514 : Strong guarantee on validation failure: the object is
515 : unchanged. If backend registration fails, the object either
516 : retains its previous socket or is left closed, depending on
517 : the backend. In all failure cases the caller retains
518 : ownership of `fd`.
519 :
520 : @param fd The native socket to adopt. On success the object
521 : owns it and closes it.
522 :
523 : @return The error code, empty on success. Validation and
524 : registration failures are normal runtime conditions when
525 : adopting foreign descriptors.
526 : */
527 : [[nodiscard]] std::error_code assign(native_handle_type fd) noexcept;
528 :
529 : /** Get the local endpoint of the socket.
530 :
531 : Returns the local address (path) to which the socket is bound.
532 : The endpoint is cached when the connection is established.
533 :
534 : @return The local endpoint, or a default endpoint if the socket
535 : is not connected.
536 : */
537 : corosio::local_endpoint local_endpoint() const noexcept;
538 :
539 : /** Get the remote endpoint of the socket.
540 :
541 : Returns the remote address (path) to which the socket is connected.
542 : The endpoint is cached when the connection is established.
543 :
544 : @return The remote endpoint, or a default endpoint if the socket
545 : is not connected.
546 : */
547 : corosio::local_endpoint remote_endpoint() const noexcept;
548 :
549 : protected:
550 : /// Default construct a closed socket for a derived class to open.
551 44 : local_stream_socket() noexcept = default;
552 :
553 : /** Adopt an existing handle.
554 :
555 : @param h The handle the socket takes ownership of.
556 : */
557 : explicit local_stream_socket(handle h) noexcept : io_object(std::move(h)) {}
558 :
559 : private:
560 : friend class local_stream_acceptor;
561 :
562 : [[nodiscard]] std::error_code
563 : open_for_family(int family, int type, int protocol) noexcept;
564 :
565 969 : inline implementation& get() const noexcept
566 : {
567 969 : return *static_cast<implementation*>(h_.get());
568 : }
569 : };
570 :
571 : } // namespace boost::corosio
572 :
573 : #endif // BOOST_COROSIO_LOCAL_STREAM_SOCKET_HPP
|
