Index/include / boost / capy / ex / strand.hpp
Prev Index Next

include/boost/capy/ex/strand.hpp

100.0% Lines (25/25) 100.0% Functions (14/14)
include/boost/capy/ex/strand.hpp
Line Hits Source Code
1 //
2 // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
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/capy
8 //
9
10 #ifndef BOOST_CAPY_EX_STRAND_HPP
11 #define BOOST_CAPY_EX_STRAND_HPP
12
13 #include <boost/capy/detail/config.hpp>
14 #include <coroutine>
15 #include <boost/capy/ex/detail/strand_service.hpp>
16
17 #include <type_traits>
18
19 namespace boost {
20 namespace capy {
21
22 //----------------------------------------------------------
23
24 /** Provides serialized coroutine execution for any executor type.
25
26 A strand wraps an inner executor and ensures that coroutines
27 dispatched through it never run concurrently. At most one
28 coroutine executes at a time within a strand, even when the
29 underlying executor runs on multiple threads.
30
31 Strands are lightweight handles that can be copied freely.
32 Copies share the same internal serialization state, so
33 coroutines dispatched through any copy are serialized with
34 respect to all other copies.
35
36 @par Invariant
37 Coroutines resumed through a strand shall not run concurrently.
38
39 @par Implementation
40 The strand uses a service-based architecture with a fixed pool
41 of 211 implementation objects. New strands hash to select an
42 impl from the pool. Strands that hash to the same index share
43 serialization, which is harmless (just extra serialization)
44 and rare with 211 buckets.
45
46 @par Executor Concept
47 This class satisfies the `Executor` concept, providing:
48 - `context()` - Returns the underlying execution context
49 - `on_work_started()` / `on_work_finished()` - Work tracking
50 - `dispatch(h)` - May run immediately if strand is idle
51 - `post(h)` - Always queues for later execution
52
53 @par Thread Safety
54 Distinct objects: Safe.
55 Shared objects: Safe.
56
57 @par Example
58 @code
59 thread_pool pool(4);
60 auto strand = make_strand(pool.get_executor());
61
62 // These coroutines will never run concurrently
63 strand.post(coro1);
64 strand.post(coro2);
65 strand.post(coro3);
66 @endcode
67
68 @tparam E The type of the underlying executor. Must
69 satisfy the `Executor` concept.
70
71 @see make_strand, Executor
72 */
73 template<typename Ex>
74 class strand
75 {
76 detail::strand_impl* impl_;
77 Ex ex_;
78
79 public:
80 /** The type of the underlying executor.
81 */
82 using inner_executor_type = Ex;
83
84 /** Construct a strand for the specified executor.
85
86 Obtains a strand implementation from the service associated
87 with the executor's context. The implementation is selected
88 from a fixed pool using a hash function.
89
90 @param ex The inner executor to wrap. Coroutines will
91 ultimately be dispatched through this executor.
92
93 @note This constructor is disabled if the argument is a
94 strand type, to prevent strand-of-strand wrapping.
95 */
96 template<typename Ex1,
97 typename = std::enable_if_t<
98 !std::is_same_v<std::decay_t<Ex1>, strand> &&
99 !detail::is_strand<std::decay_t<Ex1>>::value &&
100 std::is_convertible_v<Ex1, Ex>>>
101 explicit
102 23 strand(Ex1&& ex)
103 23 : impl_(detail::get_strand_service(ex.context())
104 23 .get_implementation())
105 23 , ex_(std::forward<Ex1>(ex))
106 {
107 23 }
108
109 /** Copy constructor.
110
111 Creates a strand that shares serialization state with
112 the original. Coroutines dispatched through either strand
113 will be serialized with respect to each other.
114 */
115 1 strand(strand const&) = default;
116
117 /** Move constructor.
118 */
119 strand(strand&&) = default;
120
121 /** Copy assignment operator.
122 */
123 strand& operator=(strand const&) = default;
124
125 /** Move assignment operator.
126 */
127 strand& operator=(strand&&) = default;
128
129 /** Return the underlying executor.
130
131 @return A const reference to the inner executor.
132 */
133 Ex const&
134 1 get_inner_executor() const noexcept
135 {
136 1 return ex_;
137 }
138
139 /** Return the underlying execution context.
140
141 @return A reference to the execution context associated
142 with the inner executor.
143 */
144 auto&
145 1 context() const noexcept
146 {
147 1 return ex_.context();
148 }
149
150 /** Notify that work has started.
151
152 Delegates to the inner executor's `on_work_started()`.
153 This is a no-op for most executor types.
154 */
155 void
156 2 on_work_started() const noexcept
157 {
158 2 ex_.on_work_started();
159 2 }
160
161 /** Notify that work has finished.
162
163 Delegates to the inner executor's `on_work_finished()`.
164 This is a no-op for most executor types.
165 */
166 void
167 2 on_work_finished() const noexcept
168 {
169 2 ex_.on_work_finished();
170 2 }
171
172 /** Determine whether the strand is running in the current thread.
173
174 @return true if the current thread is executing a coroutine
175 within this strand's dispatch loop.
176 */
177 bool
178 1 running_in_this_thread() const noexcept
179 {
180 1 return detail::strand_service::running_in_this_thread(*impl_);
181 }
182
183 /** Compare two strands for equality.
184
185 Two strands are equal if they share the same internal
186 serialization state. Equal strands serialize coroutines
187 with respect to each other.
188
189 @param other The strand to compare against.
190 @return true if both strands share the same implementation.
191 */
192 bool
193 4 operator==(strand const& other) const noexcept
194 {
195 4 return impl_ == other.impl_;
196 }
197
198 /** Post a coroutine to the strand.
199
200 The coroutine is always queued for execution, never resumed
201 immediately. When the strand becomes available, queued
202 coroutines execute in FIFO order on the underlying executor.
203
204 @par Ordering
205 Guarantees strict FIFO ordering relative to other post() calls.
206 Use this instead of dispatch() when ordering matters.
207
208 @param h The coroutine handle to post.
209 */
210 void
211 321 post(std::coroutine_handle<> h) const
212 {
213 321 detail::strand_service::post(*impl_, executor_ref(ex_), h);
214 321 }
215
216 /** Dispatch a coroutine through the strand.
217
218 Returns a handle for symmetric transfer. If the calling
219 thread is already executing within this strand, returns `h`.
220 Otherwise, the coroutine is queued and
221 `std::noop_coroutine()` is returned.
222
223 @par Ordering
224 Callers requiring strict FIFO ordering should use post()
225 instead, which always queues the coroutine.
226
227 @param h The coroutine handle to dispatch.
228
229 @return A handle for symmetric transfer or `std::noop_coroutine()`.
230 */
231 std::coroutine_handle<>
232 1 dispatch(std::coroutine_handle<> h) const
233 {
234 1 return detail::strand_service::dispatch(*impl_, executor_ref(ex_), h);
235 }
236 };
237
238 // Deduction guide
239 template<typename Ex>
240 strand(Ex) -> strand<Ex>;
241
242 } // namespace capy
243 } // namespace boost
244
245 #endif
246