Index/include / boost / corosio / native / detail / coro_op.hpp

include/boost/corosio/native/detail/coro_op.hpp

100.0% Lines (30 / 30) 66.7% Branches (4 / 6) 100.0% Functions (7 / 7)
[ ] prev/next file n p prev/next uncovered line
coro_op.hpp
f(x) Functions (7)
Function Calls Lines Branches Blocks
boost::corosio::detail::coro_op::~coro_op() :65 61379x 100.0% – 100.0% boost::corosio::detail::coro_op::canceller::operator()() const :76 2245x 100.0% – 100.0% boost::corosio::detail::coro_op::coro_op() :106 61381x 100.0% – 100.0% boost::corosio::detail::coro_op::start(std::__1::stop_token const&) :118 369963x 100.0% 100.0% 100.0% boost::corosio::detail::coro_op::destroy_awaiting() :135 1302x 100.0% 50.0% 100.0% boost::corosio::detail::coro_op::request_cancel() :147 858564x 100.0% – 100.0% boost::corosio::detail::coro_op::on_cancel() :158 204x 100.0% – 100.0%
Line Branch TLA Hits 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_NATIVE_DETAIL_CORO_OP_HPP
11 #define BOOST_COROSIO_NATIVE_DETAIL_CORO_OP_HPP
12
13 #include <boost/corosio/detail/config.hpp>
14 #include <boost/capy/continuation.hpp>
15 #include <boost/corosio/detail/object_ref.hpp>
16 #include <boost/corosio/detail/scheduler_op.hpp>
17 #include <boost/capy/ex/abandon.hpp>
18 #include <boost/capy/ex/executor_ref.hpp>
19
20 #include <atomic>
21 #include <coroutine>
22 #include <cstddef>
23 #include <memory>
24 #include <optional>
25 #include <stop_token>
26 #include <system_error>
27 #include <utility>
28
29 /*
30 Shared, non-template op envelope for every native backend — the readiness
31 reactors (epoll/kqueue/select), io_uring, and IOCP. It captures the part of
32 an async operation that is identical regardless of how completion is
33 reported: the coroutine to resume, the executor it dispatches on, the
34 output pointers, the stop_token wiring, the cancelled flag, and the
35 keepalive that holds the owning impl alive while the op is in flight.
36
37 What is deliberately NOT here (it differs by backend and stays in the
38 derived op layer):
39 - the result model: the reactors re-run the syscall and record
40 `errn`/`bytes_transferred` (reactor_op_base); io_uring stores the raw
41 `res`/`cqe_flags`; IOCP stores `dwError`/`bytes_transferred`. Each
42 decodes its own result.
43 - the submission + the kernel cancel action. Cancellation is unified only
44 at the call site via the virtual `on_cancel()` hook: the stop_callback
45 always targets `coro_op`, and each backend overrides `on_cancel()` —
46 the reactors route to the owning impl's cancel(), io_uring submits an
47 ASYNC_CANCEL SQE, IOCP calls the stored cancel_func_/CancelIoEx.
48
49 See tasks/proactor-dedup-decisions.md and coro-op-unification-scope.md.
50 */
51
52 namespace boost::corosio::detail {
53
54 /** Non-template op envelope shared by every native backend's operations.
55
56 `reactor_op_base`, `uring_op`, and `overlapped_op` all derive from this.
57 Derives from scheduler_op so ops queue intrusively and dispatch through the
58 function-pointer (io_uring/IOCP) or virtual (reactors) completion path —
59 hence both a default and a func_type constructor.
60
61 @note For IOCP, the concrete op multiply-inherits `OVERLAPPED` as its
62 first base (so `static_cast<OVERLAPPED*>` round-trips); `coro_op`
63 follows it.
64 */
65 struct coro_op : scheduler_op
66 {
67 /** Stop-callback handler: routes a stop_token firing to `on_cancel()`.
68
69 A single canceller type for both backends keeps `stop_cb` (and thus
70 `start()`) in this shared base; the backend-specific action lives
71 behind the `on_cancel()` virtual.
72 */
73 struct canceller
74 {
75 coro_op* op;
76 2245x void operator()() const noexcept
77 {
78 2245x op->on_cancel();
79 2245x }
80 };
81
82 /// The awaiting coroutine's continuation. It lives in the awaitable,
83 /// which stays in the awaiting frame until resumption, so a
84 /// completion posted through an executor never shares this op's
85 /// storage, which is reused by the next operation.
86 61381x capy::continuation* cont = nullptr;
87 capy::executor_ref ex;
88 61381x std::error_code* ec_out = nullptr;
89 61381x std::size_t* bytes_out = nullptr;
90
91 /// True for receive/read ops (drives the zero-byte == EOF decision).
92 61381x bool is_read = false;
93 /// True when the submitted buffer was zero-length (suppresses EOF).
94 61381x bool empty_buffer = false;
95
96 61381x std::atomic<bool> cancelled{false};
97 std::optional<std::stop_callback<canceller>> stop_cb;
98
99 /// Keeps the owning impl alive while the op is in flight (the kernel
100 /// owns user buffers until completion). Released when the op resumes or
101 /// abandons its coroutine (see coro_op_complete.hpp).
102 detail::object_ref object_ref_;
103
104 /// Default-construct for virtual-dispatch backends (the reactors, which
105 /// override operator()/destroy() and leave func_ null).
106 184143x coro_op() noexcept = default;
107
108 /// Construct with the completion function for func-pointer dispatch
109 /// (io_uring / IOCP completion handlers).
110 explicit coro_op(func_type func) noexcept : scheduler_op(func) {}
111
112 /** Arm the stop-token callback. Call before the op is submitted.
113
114 Resets the cancellation flag and (re)arms `stop_cb` against @a token.
115 Derived ops that carry extra pre-submit state (e.g. io_uring's
116 `sqe_set`) extend this.
117 */
118 369963x void start(std::stop_token const& token)
119 {
120 369963x cancelled.store(false, std::memory_order_relaxed);
121 369963x stop_cb.reset();
122
2/2
✓ Branch 0 taken 354340 times.
✓ Branch 1 taken 15623 times.
 369963x if (token.stop_possible())
123 15623x stop_cb.emplace(token, canceller{this});
124 369963x }
125
126 /** Give up the awaiting coroutine without resuming it.
127
128 Used when the operation is drained at teardown: the operation
129 holds the suspended coroutine, so it abandons it, which unwinds
130 its chain from the chain's owner. The keepalive is held across
131 the call because the unwind may run at once and destroy the
132 object whose impl stores this op; nothing here touches the op
133 afterwards.
134 */
135 1302x void destroy_awaiting() noexcept
136 {
137 1302x stop_cb.reset();
138 1302x auto keep = std::move(object_ref_);
139
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 1302 times.
 1302x if (auto* c = std::exchange(cont, nullptr))
140 {
141
1/2
✗ Branch 0 not taken.
✓ Branch 1 taken 1302 times.
 1302x if (c->h)
142 1302x capy::abandon(*c);
143 1302x }
144 1302x }
145
146 /// Mark this op cancellation-requested. Shared by every backend.
147 858564x void request_cancel() noexcept
148 {
149 858564x cancelled.store(true, std::memory_order_release);
150 858564x }
151
152 /** Backend cancellation hook, invoked when the stop_token fires.
153
154 The default just records the request. Backends override to also
155 drive the kernel: io_uring submits an ASYNC_CANCEL SQE; IOCP calls
156 its stored cancel_func_ (CancelIoEx / wait-reactor deregister).
157 */
158 204x virtual void on_cancel() noexcept
159 {
160 204x request_cancel();
161 204x }
162 };
163
164 } // namespace boost::corosio::detail
165
166 #endif
167