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