Index/include / boost / corosio / io / io_read_stream.hpp
Prev Index Next

include/boost/corosio/io/io_read_stream.hpp

100.0% Lines (17/17) 100.0% Functions (10/10)
include/boost/corosio/io/io_read_stream.hpp
Line Hits Source Code
1 //
2 // Copyright (c) 2026 Steve Gerbino
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_IO_IO_READ_STREAM_HPP
11 #define BOOST_COROSIO_IO_IO_READ_STREAM_HPP
12
13 #include <boost/corosio/detail/config.hpp>
14 #include <boost/corosio/io/io_object.hpp>
15 #include <boost/corosio/io_buffer_param.hpp>
16 #include <boost/capy/io_result.hpp>
17 #include <boost/capy/ex/executor_ref.hpp>
18 #include <boost/capy/ex/io_env.hpp>
19
20 #include <coroutine>
21 #include <cstddef>
22 #include <stop_token>
23 #include <system_error>
24
25 namespace boost::corosio {
26
27 /** Abstract base for streams that support async reads.
28
29 Provides the `read_some` operation via a pure virtual
30 `do_read_some` dispatch point. Concrete classes override
31 `do_read_some` to route through their implementation.
32
33 Uses virtual inheritance from @ref io_object so that
34 @ref io_stream can combine this with @ref io_write_stream
35 without duplicating the `io_object` base.
36
37 @par Thread Safety
38 Distinct objects: Safe.
39 Shared objects: Unsafe.
40
41 @see io_write_stream, io_stream, io_object
42 */
43 class BOOST_COROSIO_DECL io_read_stream : virtual public io_object
44 {
45 protected:
46 /// Awaitable for async read operations.
47 template<class MutableBufferSequence>
48 struct read_some_awaitable
49 {
50 io_read_stream& ios_;
51 MutableBufferSequence buffers_;
52 std::stop_token token_;
53 mutable std::error_code ec_;
54 mutable std::size_t bytes_transferred_ = 0;
55
56 192672 read_some_awaitable(
57 io_read_stream& ios, MutableBufferSequence buffers) noexcept
58 192672 : ios_(ios)
59 192672 , buffers_(std::move(buffers))
60 {
61 192672 }
62
63 192672 bool await_ready() const noexcept
64 {
65 192672 return token_.stop_requested();
66 }
67
68 192672 capy::io_result<std::size_t> await_resume() const noexcept
69 {
70 192672 if (token_.stop_requested())
71 196 return {make_error_code(std::errc::operation_canceled), 0};
72 192476 return {ec_, bytes_transferred_};
73 }
74
75 192672 auto await_suspend(std::coroutine_handle<> h, capy::io_env const* env)
76 -> std::coroutine_handle<>
77 {
78 192672 token_ = env->stop_token;
79 385344 return ios_.do_read_some(
80 578016 h, env->executor, buffers_, token_, &ec_, &bytes_transferred_);
81 }
82 };
83
84 /** Dispatch a read through the concrete implementation.
85
86 @param h Coroutine handle to resume on completion.
87 @param ex Executor for dispatching the completion.
88 @param buffers Target buffer sequence.
89 @param token Stop token for cancellation.
90 @param ec Output error code.
91 @param bytes Output bytes transferred.
92
93 @return Coroutine handle to resume immediately.
94 */
95 virtual std::coroutine_handle<> do_read_some(
96 std::coroutine_handle<>,
97 capy::executor_ref,
98 io_buffer_param,
99 std::stop_token,
100 std::error_code*,
101 std::size_t*) = 0;
102
103 16013 io_read_stream() noexcept = default;
104
105 /// Construct from a handle.
106 explicit io_read_stream(handle h) noexcept : io_object(std::move(h)) {}
107
108 public:
109 /** Asynchronously read data from the stream.
110
111 Suspends the calling coroutine and initiates a kernel-level
112 read. The coroutine resumes when at least one byte is read,
113 an error occurs, or the operation is cancelled.
114
115 @param buffers The buffer sequence to read data into.
116
117 @return An awaitable yielding `(error_code, std::size_t)`.
118
119 @see io_stream::write_some
120 */
121 template<capy::MutableBufferSequence MB>
122 192672 auto read_some(MB const& buffers)
123 {
124 192672 return read_some_awaitable<MB>(*this, buffers);
125 }
126 };
127
128 } // namespace boost::corosio
129
130 #endif
131