include/boost/corosio/io_context.hpp

100.0% Lines (95 / 95) 100.0% Functions (31 / 31)
io_context.hpp
f(x) Functions (31)
Function Calls Lines Blocks
boost::corosio::detail::effective_concurrency_hint(boost::corosio::io_context_options const&, unsigned int) :191 58x 100.0% 100.0% boost::corosio::io_context::frame_allocator_restore::frame_allocator_restore() :281 12322x 100.0% 100.0% boost::corosio::io_context::frame_allocator_restore::~frame_allocator_restore() :286 12322x 100.0% 100.0% boost::corosio::io_context::io_context<boost::corosio::epoll_t>(boost::corosio::epoll_t, unsigned int) :354 2053x 100.0% 86.0% boost::corosio::io_context::io_context<boost::corosio::select_t>(boost::corosio::select_t, unsigned int) :354 2057x 100.0% 86.0% boost::corosio::io_context::io_context<boost::corosio::epoll_t>(boost::corosio::epoll_t, boost::corosio::io_context_options const&, unsigned int) :389 27x 100.0% 100.0% boost::corosio::io_context::io_context<boost::corosio::select_t>(boost::corosio::select_t, boost::corosio::io_context_options const&, unsigned int) :389 26x 100.0% 100.0% boost::corosio::io_context::stop() :457 95x 100.0% 100.0% boost::corosio::io_context::stopped() const :467 1274x 100.0% 100.0% boost::corosio::io_context::restart() :477 6111x 100.0% 100.0% boost::corosio::io_context::run() :499 6815x 100.0% 100.0% boost::corosio::io_context::run_one() :522 144x 100.0% 100.0% unsigned long boost::corosio::io_context::run_for<long, std::ratio<1l, 1000l> >(std::chrono::duration<long, std::ratio<1l, 1000l> > const&) :551 37x 100.0% 100.0% unsigned long boost::corosio::io_context::run_for<long, std::ratio<1l, 1l> >(std::chrono::duration<long, std::ratio<1l, 1l> > const&) :551 812x 100.0% 88.0% unsigned long boost::corosio::io_context::run_until<std::chrono::_V2::steady_clock, std::chrono::duration<long, std::ratio<1l, 1000000000l> > >(std::chrono::time_point<std::chrono::_V2::steady_clock, std::chrono::duration<long, std::ratio<1l, 1000000000l> > > const&) :580 874x 100.0% 100.0% unsigned long boost::corosio::io_context::run_one_for<long, std::ratio<1l, 1000l> >(std::chrono::duration<long, std::ratio<1l, 1000l> > const&) :612 113x 100.0% 100.0% unsigned long boost::corosio::io_context::run_one_for<long, std::ratio<1l, 1l> >(std::chrono::duration<long, std::ratio<1l, 1l> > const&) :612 979x 100.0% 88.0% unsigned long boost::corosio::io_context::run_one_until<std::chrono::_V2::steady_clock, std::chrono::duration<long, std::ratio<1l, 1000000000l> > >(std::chrono::time_point<std::chrono::_V2::steady_clock, std::chrono::duration<long, std::ratio<1l, 1000000000l> > > const&) :641 3627x 100.0% 88.0% boost::corosio::io_context::poll() :682 1465x 100.0% 100.0% boost::corosio::io_context::poll_one() :705 84x 100.0% 100.0% boost::corosio::io_context::executor_type::executor_type() :732 2057x 100.0% 100.0% boost::corosio::io_context::executor_type::executor_type(boost::corosio::io_context&) :738 18817x 100.0% 100.0% boost::corosio::io_context::executor_type::context() const :744 46173x 100.0% 100.0% boost::corosio::io_context::executor_type::running_in_this_thread() const :753 468497x 100.0% 100.0% boost::corosio::io_context::executor_type::on_work_started() const :765 25595x 100.0% 100.0% boost::corosio::io_context::executor_type::on_work_finished() const :774 25595x 100.0% 100.0% boost::corosio::io_context::executor_type::dispatch(boost::capy::continuation&) const :793 468490x 100.0% 100.0% boost::corosio::io_context::executor_type::post(boost::capy::continuation&) const :812 236933x 100.0% 100.0% boost::corosio::io_context::executor_type::post(std::__n4861::coroutine_handle<void>) const :837 3862x 100.0% 100.0% boost::corosio::io_context::executor_type::operator==(boost::corosio::io_context::executor_type const&) const :846 2x 100.0% 100.0% boost::corosio::io_context::get_executor() const :862 18817x 100.0% 100.0%
Line TLA Hits Source Code
1 //
2 // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
3 // Copyright (c) 2026 Steve Gerbino
4 // Copyright (c) 2026 Michael Vandeberg
5 //
6 // Distributed under the Boost Software License, Version 1.0. (See accompanying
7 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
8 //
9 // Official repository: https://github.com/cppalliance/corosio
10 //
11
12 #ifndef BOOST_COROSIO_IO_CONTEXT_HPP
13 #define BOOST_COROSIO_IO_CONTEXT_HPP
14
15 #include <boost/corosio/detail/config.hpp>
16 #include <boost/corosio/detail/platform.hpp>
17 #include <boost/corosio/detail/scheduler.hpp>
18 #include <boost/capy/continuation.hpp>
19 #include <boost/capy/ex/execution_context.hpp>
20 #include <boost/capy/ex/frame_allocator.hpp>
21
22 #include <chrono>
23 #include <coroutine>
24 #include <cstddef>
25 #include <limits>
26 #include <thread>
27
28 namespace boost::corosio {
29
30 /** Selects which internal locks the scheduler and reactor elide,
31 trading thread-safety guarantees for reduced synchronization
32 overhead.
33
34 This is the analog of Boost.Asio's `SAFE` / `UNSAFE_IO` / `UNSAFE`
35 concurrency hint constants. The tier is chosen explicitly, not derived
36 from the `concurrency_hint`. (The reverse does apply: a lockless tier
37 reduces the effective hint used for performance tuning to 1.)
38
39 @see @ref io_context_options::locking
40 */
41 enum class locking_mode
42 {
43 /** Full thread safety (default). All locks enabled; equivalent to
44 Boost.Asio's `SAFE`/`DEFAULT`. Any thread may use the context. */
45 safe,
46
47 /** Disable only the per-descriptor I/O locks; keep scheduler locking.
48 Equivalent to Boost.Asio's `UNSAFE_IO`. A single thread must run
49 and drive the context. Resolver and POSIX file services remain
50 available, because they rely on scheduler locking, which stays
51 on. */
52 unsafe_io,
53
54 /** Disable all locking (fully lockless). Equivalent to Boost.Asio's
55 `UNSAFE`.
56
57 @par Restrictions
58 - Only one thread may call `run()` (or any run variant).
59 - Posting work from another thread is undefined behavior.
60 - DNS resolution returns `operation_not_supported`, except on
61 IOCP, whose resolver does not use the thread pool.
62 - POSIX file I/O returns `operation_not_supported`.
63 - `win_object_handle::assign()` returns `operation_not_supported`.
64 - Signal sets should not be shared across contexts. */
65 unsafe
66 };
67
68 /** Configures scheduler and reactor tuning for an @ref io_context.
69
70 All fields have defaults that match the library's built-in
71 values, so constructing a default `io_context_options` produces
72 identical behavior to an unconfigured context.
73
74 Options that apply only to a specific backend family are ignored
75 when the active backend does not use them. The exceptions are
76 `max_events_per_poll` and `inline_budget_max`, which are
77 range-checked on every platform with a reactor backend.
78
79 @par Example
80 @par !example configure
81
82 @see @ref io_context, @ref native_io_context
83 */
84 struct io_context_options
85 {
86 /** Maximum events fetched per reactor poll call.
87
88 Controls the buffer size passed to `epoll_wait()` or
89 `kevent()`. Larger values reduce syscall frequency under
90 high load. Smaller values improve fairness between
91 connections. Must be in [ 1, `INT_MAX` ]. Where epoll is
92 available, it must also not exceed
93 `INT_MAX / sizeof(epoll_event)`, the most events one epoll wait
94 accepts. Validated on platforms with a reactor backend,
95 whichever backend is active, but only the epoll and kqueue
96 backends use it.
97 */
98 unsigned max_events_per_poll = 128;
99
100 /** Starting inline completion budget per handler chain.
101
102 After a posted handler executes, the reactor grants this
103 many speculative inline completions before forcing a
104 re-queue. Applies to reactor backends only.
105
106 @note Constructing an `io_context` with `concurrency_hint > 1`
107 and all three budget fields at their defaults overrides them to
108 disable inline completion, giving post-everything mode.
109 Multi-thread workloads benefit from cross-thread work-stealing.
110 Setting any budget field to a non-default
111 value disables the override.
112 */
113 unsigned inline_budget_initial = 2;
114
115 /** Hard ceiling on adaptive inline budget ramp-up.
116
117 The budget doubles each cycle it is fully consumed, up to
118 this limit. Must be in [ 0, `INT_MAX` ]; validated on
119 platforms with a reactor backend, whichever backend is
120 active. Applies to reactor backends only.
121 */
122 unsigned inline_budget_max = 16;
123
124 /** Inline budget when no other thread assists the reactor.
125
126 When only one thread is running the event loop, this
127 value caps the inline budget to preserve fairness.
128 Applies to reactor backends only.
129 */
130 unsigned unassisted_budget = 4;
131
132 /** Thread pool size for blocking I/O (file I/O, DNS resolution).
133
134 Sets the number of worker threads in the shared thread pool
135 used by POSIX file services and DNS resolution. Must be at
136 least 1. Applies to POSIX backends only; ignored on IOCP
137 where file I/O uses native overlapped I/O.
138 */
139 unsigned thread_pool_size = 1;
140
141 /** Thread-safety tier. See @ref locking_mode for the tiers and their
142 restrictions.
143 */
144 locking_mode locking = locking_mode::safe;
145
146 /** Enable IORING_SETUP_SQPOLL on the io_uring backend.
147
148 With SQPOLL, the kernel forks a thread that busy-polls the
149 submission ring. Submission becomes a userspace-only memory
150 store, which eliminates the `io_uring_enter` syscall on the submit
151 path. Most useful for sustained traffic. Idle thread parks
152 after `sq_thread_idle_ms` of no activity.
153
154 Independent of `locking`. Default: off.
155
156 Ignored on non-io_uring backends.
157 */
158 bool enable_sqpoll = false;
159
160 /** SQ-poll idle timeout in milliseconds.
161
162 After this many ms of no submissions, the kernel polling
163 thread sleeps. The next submit re-wakes it via SQ_WAKEUP. 0
164 means use the kernel default (1ms). Recommended for bursty
165 workloads: 100-1000ms (avoids park/unpark thrash).
166
167 Ignored unless `enable_sqpoll` is true. Ignored on
168 non-io_uring backends.
169 */
170 unsigned sq_thread_idle_ms = 0;
171
172 /** Pin the SQ-poll kernel thread to this CPU.
173
174 -1 means do not pin (kernel scheduler picks). Pinning off
175 the dispatch core is recommended on latency-sensitive
176 deployments to avoid cache contention.
177
178 Ignored unless `enable_sqpoll` is true. Ignored on
179 non-io_uring backends.
180 */
181 int sq_thread_cpu = -1;
182 };
183
184 namespace detail {
185 class timer_service;
186
187 /** Return the hint used for performance tuning: the lockless tiers are
188 single-threaded, so their effective hint is 1 whatever the caller passed.
189 */
190 inline unsigned
191 58x effective_concurrency_hint(
192 io_context_options const& opts, unsigned hint) noexcept
193 {
194 58x return opts.locking == locking_mode::safe ? hint : 1u;
195 }
196 } // namespace detail
197
198 /** Runs asynchronous operations and owns the I/O backend that drives them.
199
200 The `io_context` provides an execution environment for async
201 operations. It maintains a queue of pending work items and
202 processes them when `run()` is called.
203
204 The default and unsigned constructors select the platform's
205 native backend:
206 - Windows: IOCP
207 - Linux: epoll
208 - BSD/macOS: kqueue
209 - Other POSIX: select
210
211 The template constructor accepts a backend tag value to
212 choose a specific backend at compile time:
213
214 @par Example
215 @par !example construct
216
217 @pre The context must outlive every operation posted or dispatched
218 through its executor. No thread may be executing a run variant when
219 the context is destroyed. Posting to the context
220 concurrently with, or after, its destruction is undefined
221 behavior. For a safe teardown, first stop submitting new work.
222 Then let every `run()` call return; each returns once no
223 outstanding work remains. Finally join the threads that ran the
224 loop. Only then destroy the context. Work started with
225 `capy::run` / `capy::run_async` is work-tracked, so a normal
226 `run()` completion already waits for it. Destroying the context
227 abandons every coroutine still suspended in it (see
228 @ref ~io_context).
229
230 @par Exception Safety
231 A context that constructs is usable. The infrastructure its backend
232 needs — the completion port, the ring, the reactor's wakeup channel
233 — is created during construction. A system that refuses it therefore
234 throws from the constructor rather than from the first operation.
235 The failed construction leaves nothing open.
236
237 An operation that completes resumes its coroutine through the
238 executor the coroutine awaited it on. If that executor's `post` or
239 `dispatch` throws, `std::terminate` is called.
240
241 @par Thread Safety
242 Distinct objects: Safe.@n
243 Shared objects: Safe, unless the context was constructed with a
244 lockless @ref io_context_options::locking tier (`unsafe_io` or
245 `unsafe`), in which case a single thread must drive it.
246
247 @see @ref epoll_t, @ref select_t, @ref kqueue_t, @ref iocp_t
248 */
249 class BOOST_COROSIO_DECL io_context : public capy::execution_context
250 {
251 /// Reject invalid options before the backend is constructed.
252 void apply_options_pre_(io_context_options const& opts);
253
254 /** Create the blocking-I/O thread pool, apply runtime tuning to the
255 scheduler and finish bringing the backend up. The tail of every
256 options constructor. The backend infrastructure whose setup reads
257 these options is created here, so a failure to create it throws
258 from the constructor. */
259 void apply_options_post_(
260 io_context_options const& opts, unsigned concurrency_hint);
261
262 /** Create the blocking-I/O thread pool and apply only the decomposed
263 threading configuration (locking tiers), then finish bringing the
264 backend up. The tail of every plain constructor. Unlike the
265 options constructors, it deliberately leaves the reactor budget
266 at its defaults rather than engaging the multi-thread
267 post-everything heuristic. */
268 void apply_threading_(io_context_options const& opts);
269
270 protected:
271 detail::scheduler* sched_;
272
273 // Resuming a chain installs its frame allocator on the running
274 // thread; a run call puts back what it found, so a coroutine created
275 // afterwards never reaches a resource that died with those frames.
276 struct frame_allocator_restore
277 {
278 std::pmr::memory_resource* saved =
279 capy::get_current_frame_allocator();
280
281 12322x frame_allocator_restore() = default;
282 frame_allocator_restore(frame_allocator_restore const&) = delete;
283 frame_allocator_restore&
284 operator=(frame_allocator_restore const&) = delete;
285
286 12322x ~frame_allocator_restore()
287 {
288 12322x capy::set_current_frame_allocator(saved);
289 12322x }
290 };
291
292 public:
293 /** Dispatches and posts work to this context; see the
294 executor_type definition below. */
295 class executor_type;
296
297 /** Construct with default concurrency and platform backend.
298
299 Uses `std::thread::hardware_concurrency()` (floored to 1, in
300 case it reports 0) as the concurrency hint, and the default
301 @ref locking_mode::safe tier. Select a lockless tier via
302 @ref io_context_options::locking.
303
304 @throws std::system_error If the backend's infrastructure
305 could not be created.
306 */
307 io_context();
308
309 /** Construct with a concurrency hint and platform backend.
310
311 @param concurrency_hint Hint for the number of threads
312 that calls `run()`.
313
314 @throws std::system_error If the backend's infrastructure
315 could not be created.
316 */
317 explicit io_context(unsigned concurrency_hint);
318
319 /** Construct with runtime tuning options and platform backend.
320
321 @param opts Runtime options controlling scheduler and
322 service behavior.
323 @param concurrency_hint Hint for the number of threads
324 that calls `run()`.
325
326 @throws std::invalid_argument If `opts.thread_pool_size` is
327 less than 1 (POSIX), `opts.max_events_per_poll` is outside
328 the range its member documents, or `opts.inline_budget_max`
329 exceeds `INT_MAX` (platforms with a reactor backend).
330
331 @throws std::system_error If the backend's infrastructure
332 could not be created.
333 */
334 explicit io_context(
335 io_context_options const& opts,
336 unsigned concurrency_hint = std::thread::hardware_concurrency());
337
338 /** Construct with an explicit backend tag.
339
340 @tparam Backend A backend tag type that provides a static
341 `construct(capy::execution_context&, unsigned)` factory
342 used to build the scheduler.
343
344 @param backend The backend tag value selecting the I/O
345 multiplexer (e.g. `corosio::epoll`).
346 @param concurrency_hint Hint for the number of threads
347 that calls `run()`.
348
349 @throws std::system_error If the backend's infrastructure
350 could not be created.
351 */
352 template<class Backend>
353 requires requires { Backend::construct; }
354 4110x explicit io_context(
355 [[maybe_unused]] Backend backend,
356 unsigned concurrency_hint = std::thread::hardware_concurrency())
357 : capy::execution_context(this)
358 4110x , sched_(nullptr)
359 {
360 4110x sched_ = &Backend::construct(*this, concurrency_hint);
361 // Apply threading config only (locking tier). Unlike the options
362 // ctor, the plain path leaves the reactor budget at its defaults.
363 4094x apply_threading_(io_context_options{});
364 4110x }
365
366 /** Construct with an explicit backend tag and runtime options.
367
368 @tparam Backend A backend tag type that provides a static
369 `construct(capy::execution_context&, unsigned)` factory
370 used to build the scheduler.
371
372 @param backend The backend tag value selecting the I/O
373 multiplexer (e.g. `corosio::epoll`).
374 @param opts Runtime options controlling scheduler and
375 service behavior.
376 @param concurrency_hint Hint for the number of threads
377 that calls `run()`.
378
379 @throws std::invalid_argument If `opts.thread_pool_size` is
380 less than 1 (POSIX), `opts.max_events_per_poll` is outside
381 the range its member documents, or `opts.inline_budget_max`
382 exceeds `INT_MAX` (platforms with a reactor backend).
383
384 @throws std::system_error If the backend's infrastructure
385 could not be created.
386 */
387 template<class Backend>
388 requires requires { Backend::construct; }
389 53x explicit io_context(
390 [[maybe_unused]] Backend backend,
391 io_context_options const& opts,
392 unsigned concurrency_hint = std::thread::hardware_concurrency())
393 : capy::execution_context(this)
394 53x , sched_(nullptr)
395 {
396 53x apply_options_pre_(opts);
397 // Effective hint (1 for lockless tiers); see effective_concurrency_hint.
398 unsigned const eff =
399 41x detail::effective_concurrency_hint(opts, concurrency_hint);
400 41x sched_ = &Backend::construct(*this, eff);
401 41x apply_options_post_(opts, eff);
402 53x }
403
404 /** Destroy the context, its services and the coroutines it holds.
405
406 The destructor stops the loop and destroys every service. Each
407 coroutine suspended in an operation of this context, or posted to
408 it and not yet resumed, is abandoned. Its chain is unwound from
409 the top, on the executor of the chain's owner (see
410 `capy::abandon`). The precondition below makes that executor this
411 context's, so the unwind runs during this destruction.
412
413 @pre No thread is executing a run variant.
414
415 @pre No work crosses into another execution context. A chain
416 held here must be owned on this context. No frame of a chain
417 owned elsewhere may own I/O objects of this context, or wait
418 on a primitive that a chain held here owns. Such a chain's
419 unwind would run on the other context after this one is gone,
420 whatever the order of destruction. Stop such work and run both
421 contexts until it ends before destroying either.
422
423 @note Every service gives up its work while the services shut
424 down, so nothing is left when they are destroyed. Work posted
425 after that anyway, for example from a service's destructor, is
426 abandoned while the services are being destroyed. Its
427 destructors must not use any service.
428 */
429 ~io_context();
430
431 /// Copy construction is disabled; the context owns its services.
432 io_context(io_context const&) = delete;
433 /// Copy assignment is disabled; the context owns its services.
434 io_context& operator=(io_context const&) = delete;
435
436 /** Return an executor for this context.
437
438 The returned executor can be used to dispatch coroutines
439 and post work items to this context.
440
441 @return An executor associated with this context.
442 */
443 executor_type get_executor() const noexcept;
444
445 /** Signal the context to stop processing.
446
447 This causes `run()` to return as soon as possible. Any pending
448 work items remain queued.
449
450 On Windows, queued work may still run after `stop()`: each
451 `run()` call sees the stop only when it reaches the stop's wakeup.
452
453 @throws std::system_error on Windows if the wakeup cannot be
454 queued, which leaves blocked `run()` callers unable to wake
455 until a later call succeeds.
456 */
457 95x void stop()
458 {
459 95x sched_->stop();
460 95x }
461
462 /** Return whether the context stopped.
463
464 @return `true` after a call to `stop()` with no later
465 call to `restart()`.
466 */
467 1274x bool stopped() const noexcept
468 {
469 1274x return sched_->stopped();
470 }
471
472 /** Restart the context after being stopped.
473
474 This function must be called before `run()` can be called
475 again after a call to `stop()`.
476 */
477 6111x void restart()
478 {
479 6111x sched_->restart();
480 6111x }
481
482 /** Process all pending work items.
483
484 This function blocks until it executes all pending work items,
485 or until `stop()` is called. The context is stopped
486 when there is no more outstanding work.
487
488 @throws std::system_error if waiting on the operating system's
489 event demultiplexer fails other than by interruption or
490 another transient condition; the context can no longer
491 dispatch work. On Windows, also if a wakeup needed to
492 stop the context cannot be queued.
493
494 @note The context must be restarted with `restart()` before
495 calling this function again after it returns.
496
497 @return The number of handlers executed.
498 */
499 6815x std::size_t run()
500 {
501 6815x frame_allocator_restore restore;
502 13625x return sched_->run();
503 6815x }
504
505 /** Process at most one pending work item.
506
507 This function blocks until it executes one work item
508 or `stop()` is called. The context is stopped when there
509 is no more outstanding work.
510
511 @throws std::system_error if waiting on the operating system's
512 event demultiplexer fails other than by interruption or
513 another transient condition; the context can no longer
514 dispatch work. On Windows, also if a wakeup needed to
515 stop the context cannot be queued.
516
517 @note The context must be restarted with `restart()` before
518 calling this function again after it returns.
519
520 @return The number of handlers executed (0 or 1).
521 */
522 144x std::size_t run_one()
523 {
524 144x frame_allocator_restore restore;
525 286x return sched_->run_one();
526 144x }
527
528 /** Process work items for the specified duration.
529
530 This function blocks until it has executed work items for the
531 specified duration, or until `stop()` is called. The context
532 is stopped when there is no more outstanding work.
533
534 A duration of zero or less returns 0 at once, without running
535 any work or stopping the context.
536
537 @throws std::system_error if waiting on the operating system's
538 event demultiplexer fails other than by interruption or
539 another transient condition; the context can no longer
540 dispatch work. On Windows, also if a wakeup needed to
541 stop the context cannot be queued.
542
543 @note The context must be restarted with `restart()` before
544 calling this function again after it returns.
545
546 @param rel_time The duration for which to process work.
547
548 @return The number of handlers executed.
549 */
550 template<class Rep, class Period>
551 849x std::size_t run_for(std::chrono::duration<Rep, Period> const& rel_time)
552 {
553 849x return run_until(std::chrono::steady_clock::now() + rel_time);
554 }
555
556 /** Process work items until the specified time.
557
558 This function blocks until the specified time is reached
559 or `stop()` is called. The context is stopped when there
560 is no more outstanding work.
561
562 A time that has already passed returns 0 at once, without
563 running any work or stopping the context.
564
565 @throws std::system_error if waiting on the operating system's
566 event demultiplexer fails other than by interruption or
567 another transient condition; the context can no longer
568 dispatch work. On Windows, also if a wakeup needed to
569 stop the context cannot be queued.
570
571 @note The context must be restarted with `restart()` before
572 calling this function again after it returns.
573
574 @param abs_time The time point until which to process work.
575
576 @return The number of handlers executed.
577 */
578 template<class Clock, class Duration>
579 std::size_t
580 874x run_until(std::chrono::time_point<Clock, Duration> const& abs_time)
581 {
582 874x std::size_t n = 0;
583 2505x while (run_one_until(abs_time))
584 1631x if (n != (std::numeric_limits<std::size_t>::max)())
585 1631x ++n;
586 870x return n;
587 }
588
589 /** Process at most one work item for the specified duration.
590
591 This function blocks until it executes one work item,
592 the specified duration has elapsed, or `stop()` is called.
593 The context is stopped when there is no more outstanding work.
594
595 A duration of zero or less returns 0 at once, without running
596 any work or stopping the context.
597
598 @throws std::system_error if waiting on the operating system's
599 event demultiplexer fails other than by interruption or
600 another transient condition; the context can no longer
601 dispatch work. On Windows, also if a wakeup needed to
602 stop the context cannot be queued.
603
604 @note The context must be restarted with `restart()` before
605 calling this function again after it returns.
606
607 @param rel_time The duration for which the call may block.
608
609 @return The number of handlers executed (0 or 1).
610 */
611 template<class Rep, class Period>
612 1092x std::size_t run_one_for(std::chrono::duration<Rep, Period> const& rel_time)
613 {
614 1092x return run_one_until(std::chrono::steady_clock::now() + rel_time);
615 }
616
617 /** Process at most one work item until the specified time.
618
619 This function blocks until it executes one work item,
620 the specified time is reached, or `stop()` is called.
621 The context is stopped when there is no more outstanding work.
622
623 A time that has already passed returns 0 at once, without
624 running any work or stopping the context.
625
626 @throws std::system_error if waiting on the operating system's
627 event demultiplexer fails other than by interruption or
628 another transient condition; the context can no longer
629 dispatch work. On Windows, also if a wakeup needed to
630 stop the context cannot be queued.
631
632 @note The context must be restarted with `restart()` before
633 calling this function again after it returns.
634
635 @param abs_time The time point until which the call may block.
636
637 @return The number of handlers executed (0 or 1).
638 */
639 template<class Clock, class Duration>
640 std::size_t
641 3627x run_one_until(std::chrono::time_point<Clock, Duration> const& abs_time)
642 {
643 3627x frame_allocator_restore restore;
644 3627x typename Clock::time_point now = Clock::now();
645 3814x while (now < abs_time)
646 {
647 3742x auto rel_time = abs_time - now;
648 3742x if (rel_time > std::chrono::seconds(1))
649 3594x rel_time = std::chrono::seconds(1);
650
651 3742x std::size_t s = sched_->wait_one(
652 static_cast<long>(
653 3750x std::chrono::duration_cast<std::chrono::microseconds>(
654 rel_time)
655 3742x .count()));
656
657 3734x if (s || stopped())
658 3547x return s;
659
660 187x now = Clock::now();
661 }
662 72x return 0;
663 3627x }
664
665 /** Process all ready work items without blocking.
666
667 This function executes all work items that are ready to run
668 without blocking for more work. The context is stopped
669 when there is no more outstanding work.
670
671 @throws std::system_error if waiting on the operating system's
672 event demultiplexer fails other than by interruption or
673 another transient condition; the context can no longer
674 dispatch work. On Windows, also if a wakeup needed to
675 stop the context cannot be queued.
676
677 @note The context must be restarted with `restart()` before
678 calling this function again after it returns.
679
680 @return The number of handlers executed.
681 */
682 1465x std::size_t poll()
683 {
684 1465x frame_allocator_restore restore;
685 2928x return sched_->poll();
686 1465x }
687
688 /** Process at most one ready work item without blocking.
689
690 This function executes at most one work item that is ready
691 to run without blocking for more work. The context is
692 stopped when there is no more outstanding work.
693
694 @throws std::system_error if waiting on the operating system's
695 event demultiplexer fails other than by interruption or
696 another transient condition; the context can no longer
697 dispatch work. On Windows, also if a wakeup needed to
698 stop the context cannot be queued.
699
700 @note The context must be restarted with `restart()` before
701 calling this function again after it returns.
702
703 @return The number of handlers executed (0 or 1).
704 */
705 84x std::size_t poll_one()
706 {
707 84x frame_allocator_restore restore;
708 166x return sched_->poll_one();
709 84x }
710 };
711
712 /** Dispatches and posts work to an I/O context.
713
714 The executor provides the interface for posting work items and
715 dispatching coroutines to the associated context. It satisfies
716 the `capy::Executor` concept.
717
718 Executors are lightweight handles that can be copied and compared
719 for equality. Two executors compare equal if they refer to the
720 same context.
721
722 @par Thread Safety
723 Distinct objects: Safe.@n
724 Shared objects: Safe.
725 */
726 class io_context::executor_type
727 {
728 io_context* ctx_ = nullptr;
729
730 public:
731 /** Constructs an executor not associated with any context. */
732 2057x executor_type() = default;
733
734 /** Construct an executor from a context.
735
736 @param ctx The context to associate with this executor.
737 */
738 18817x explicit executor_type(io_context& ctx) noexcept : ctx_(&ctx) {}
739
740 /** Return a reference to the associated execution context.
741
742 @return Reference to the context.
743 */
744 46173x io_context& context() const noexcept
745 {
746 46173x return *ctx_;
747 }
748
749 /** Check if the current thread is running this executor's context.
750
751 @return `true` if `run()` is being called on this thread.
752 */
753 468497x bool running_in_this_thread() const noexcept
754 {
755 // The innermost scheduler answers the common case without a
756 // virtual call or a frame walk.
757 492794x return detail::running_scheduler.get() == ctx_->sched_ ||
758 492794x ctx_->sched_->running_in_this_thread();
759 }
760
761 /** Informs the executor that work is beginning.
762
763 Must be paired with `on_work_finished()`.
764 */
765 25595x void on_work_started() const noexcept
766 {
767 25595x ctx_->sched_->work_started();
768 25595x }
769
770 /** Informs the executor that work has completed.
771
772 @pre A preceding call to `on_work_started()` on an equal executor.
773 */
774 25595x void on_work_finished() const noexcept
775 {
776 25595x ctx_->sched_->work_finished();
777 25595x }
778
779 /** Dispatch a continuation.
780
781 Returns a handle for symmetric transfer. If called from
782 within `run()`, returns `c.h`. Otherwise posts `c` for
783 later execution and returns `std::noop_coroutine()`.
784
785 @param c The continuation to dispatch.
786
787 @return A handle for symmetric transfer or `std::noop_coroutine()`.
788
789 @pre The associated context must outlive this call. Dispatching
790 concurrently with, or after, the context's destruction is
791 undefined behavior.
792 */
793 468490x std::coroutine_handle<> dispatch(capy::continuation& c) const
794 {
795 468490x if (running_in_this_thread())
796 444196x return c.h;
797 24294x post(c);
798 24294x return std::noop_coroutine();
799 }
800
801 /** Post a continuation for deferred execution.
802
803 Enqueues `c` directly on the scheduler's ready queue.
804 No heap allocation occurs.
805
806 @param c The continuation to enqueue.
807
808 @pre The associated context must outlive this call. Posting
809 concurrently with, or after, the context's destruction is
810 undefined behavior.
811 */
812 236933x void post(capy::continuation& c) const
813 {
814 236933x ctx_->sched_->post(c);
815 236933x }
816
817 /** Post a bare coroutine handle for deferred execution.
818
819 Heap-allocates a `scheduler_op` to wrap the handle. A caller
820 that already owns a `capy::continuation` can post it directly
821 via the `post(capy::continuation&)` overload to avoid the
822 allocation.
823
824 A handle still queued when the context is torn down is
825 destroyed alone, since it carries no owner to unwind its chain
826 from. Post a coroutine that another frame awaits through the
827 `post(capy::continuation&)` overload, with its owner set.
828
829 @param h The coroutine handle to post.
830
831 @pre The associated context must outlive this call. Posting
832 concurrently with, or after, the context's destruction is
833 undefined behavior.
834
835 @pre Nothing awaits `h`.
836 */
837 3862x void post(std::coroutine_handle<> h) const
838 {
839 3862x ctx_->sched_->post(h);
840 3862x }
841
842 /** Compare two executors for equality.
843
844 @return `true` if both executors refer to the same context.
845 */
846 2x bool operator==(executor_type const& other) const noexcept
847 {
848 2x return ctx_ == other.ctx_;
849 }
850
851 /** Compare two executors for inequality.
852
853 @return `true` if the executors refer to different contexts.
854 */
855 bool operator!=(executor_type const& other) const noexcept
856 {
857 return ctx_ != other.ctx_;
858 }
859 };
860
861 inline io_context::executor_type
862 18817x io_context::get_executor() const noexcept
863 {
864 18817x return executor_type(const_cast<io_context&>(*this));
865 }
866
867 } // namespace boost::corosio
868
869 #endif // BOOST_COROSIO_IO_CONTEXT_HPP
870