VLink  2.3.0
A high-performance communication middleware
coroutine.h
浏览该文件的文档.
1 /*
2  * Copyright (C) 2026 by Thun Lu. All rights reserved.
3  * Author: Thun Lu <thun.lu@zohomail.cn>
4  * Repo: https://github.com/thun-res/vlink
5  * _ __ __ _ __
6  * | | / / / / (_) ____ / /__
7  * | | / / / / / / / __ \ / //_/
8  * | |/ / / /___ / / / / / / / ,<
9  * |___/ /_____/ /_/ /_/ /_/ /_/|_|
10  *
11  * Licensed under the Apache License, Version 2.0 (the "License");
12  * you may not use this file except in compliance with the License.
13  * You may obtain a copy of the License at
14  *
15  * http://www.apache.org/licenses/LICENSE-2.0
16  *
17  * Unless required by applicable law or agreed to in writing, software
18  * distributed under the License is distributed on an "AS IS" BASIS,
19  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20  * See the License for the specific language governing permissions and
21  * limitations under the License.
22  */
23 
24 /**
25  * @file coroutine.h
26  * @brief Stackless C++20 coroutine layer that resumes work onto @c MessageLoop threads.
27  *
28  * @details
29  * Adds an additive coroutine binding atop @c MessageLoop, @c GraphTask and @c Schedule. Every
30  * awaiter eventually re-enters the target loop through @c MessageLoop::post_task or
31  * @c MessageLoop::exec_task; the loop itself is unchanged. The layer compiles in only when
32  * @c VLINK_ENABLE_COROUTINE is defined (auto-enabled when @c VLINK_ENABLE_CXX_STD_20 is set and
33  * the toolchain advertises @c __cpp_impl_coroutine and @c __cpp_lib_coroutine); otherwise the
34  * file is empty. The canonical namespace is @c vlink::Coroutine with @c vlink::Co as a short
35  * alias.
36  *
37  * @par State machine of a coroutine resume
38  *
39  * @verbatim
40  * +----------+ co_spawn / +-----------+ awaiter +-------------+
41  * | created | -- co_await ---> | suspended | -- ready -> | resumed on |
42  * +----------+ +-----------+ | target loop |
43  * | ^ +-------------+
44  * | | |
45  * | queue full (kRetry) | | co_return
46  * | +--------------------------+ v
47  * | | +-------------+
48  * | | helper thread retries every ~1ms | finished |
49  * v v +-------------+
50  * +-----------+ loop closed (kClosed)
51  * | failed | --> await_resume throws runtime_error / OperationCancelled
52  * +-----------+
53  * @endverbatim
54  *
55  * @par Awaitable surface
56  *
57  * | Category | Symbol | Purpose |
58  * | ------------- | --------------------------------- | ------------------------------------ |
59  * | Core type | @c Task<TypeT> | Lazily started awaitable |
60  * | Awaiter | @c schedule(loop, prio) | Hop onto @p loop 's thread |
61  * | Awaiter | @c yield(loop, prio) | Re-post to the back of the queue |
62  * | Awaiter | @c delay_ms(loop, ms, prio) | Non-blocking sleep |
63  * | Awaiter | @c await_future(loop, fut) | Wait on @c std::future |
64  * | Entry point | @c co_spawn(loop, task) | Fire-and-forget @c Task<void> |
65  * | Entry point | @c co_spawn(loop, task, on_done) | Spawn with completion callback |
66  * | Entry point | @c co_spawn_with_priority(...) | Same overloads with priority |
67  * | Bridge | @c exec(loop, config, fn) | Wrap @c MessageLoop::exec_task |
68  * | Bridge | @c await_graph(loop, graph) | Wait on a @c GraphTask node |
69  * | Orchestration | @c when_all(loop, tasks) | Join all, collect results |
70  * | Orchestration | @c when_any(loop, tasks) | First success and its index |
71  * | Orchestration | @c sequence(loop, tasks) | Run in order |
72  *
73  * @par Frame allocation
74  * Coroutine frames flow through @c vlink::MemoryPool::global_instance() via the
75  * @c operator @c new / @c operator @c delete overloads on @c TaskPromise and
76  * @c DetachedTask::promise_type. The allocator throws @c std::bad_alloc on pool exhaustion;
77  * there is no custom-allocator template parameter.
78  *
79  * @par Lock order
80  * @c MessageLoop::AliveState::mtx -> @c MessageLoop::Impl::mtx -> @c TaskHandle::State::mtx ->
81  * awaiter shared-state mutex. Each awaiter owns its own state object that holds the suspended
82  * coroutine handle. When the target loop closes mid-resume the handle is released on the
83  * @c FutureWaitLoop helper thread via a queued retry; callers must therefore not assume
84  * @c await_resume runs on the original loop.
85  *
86  * @par Cancellation contract
87  * - @c await_future rethrows the promise's stored exception via @c future.get(). When the
88  * target loop closes before the ready future can be posted back, @c await_resume throws
89  * @c vlink::Exception::OperationCancelled.
90  * - @c await_graph normally returns @c void; on the late-closure path it throws
91  * @c vlink::Exception::OperationCancelled.
92  * - @c schedule / @c yield / @c delay_ms retry posting through the @c FutureWaitLoop helper on
93  * @c kRetry; once @c detail::kMaxResumePostRetry (@c 30000 ticks of approximately one
94  * millisecond each) is exhausted, or the loop reports @c kClosed, @c await_resume throws
95  * @c std::runtime_error with a descriptive message.
96  *
97  * @par FutureWaitLoop
98  * A process-wide helper thread polls every registered awaiter at a roughly one-millisecond
99  * cadence. Concurrent use of @c await_future shares this thread; latency is bounded by the
100  * cadence plus the target loop's task dispatch delay.
101  *
102  * @par Priority remap on full-queue loops
103  * On @c kPriorityType loops the post helper remaps @c MessageLoop::kNoPriority to
104  * @c MessageLoop::kNormalPriority so default-priority resumes do not sink to the queue tail.
105  *
106  * @par Alive-state mutex hold time
107  * @c post_callback_if_alive acquires @c MessageLoop::AliveState::mtx only briefly; the inner
108  * @c post_callback path uses @c TaskOverflowPolicy::kReject so the alive-state mutex is never
109  * held across a sleep or backoff.
110  *
111  * @par Example
112  * @code
113  * vlink::MessageLoop loop;
114  * loop.async_run();
115  *
116  * vlink::Co::Task<> my_routine(vlink::MessageLoop& loop, int* counter) {
117  * co_await vlink::Co::delay_ms(loop, 100);
118  * ++(*counter);
119  * co_await vlink::Co::yield(loop);
120  * ++(*counter);
121  * }
122  *
123  * int counter = 0;
124  * vlink::Co::co_spawn(loop, my_routine(loop, &counter));
125  * @endcode
126  *
127  * @warning Passing a coroutine lambda as a temporary, for example
128  * @code
129  * co_spawn(loop, []() -> Task<> { co_await ... ; }());
130  * @endcode
131  * destroys the lambda object at the end of the full-expression -- long before the
132  * coroutine body runs. Any captured state (including @c [&] and @c [=]) becomes a
133  * dangling reference. Always thread captures through function parameters so the
134  * compiler copies them into the coroutine frame.
135  */
136 
137 #pragma once
138 
139 #include "../version.h"
140 
141 #ifdef VLINK_ENABLE_CXX_STD_20
142 #if defined(__cpp_impl_coroutine) && __has_include(<coroutine>)
143 #include <coroutine>
144 #endif
145 #if defined(__cpp_lib_coroutine)
146 #ifndef VLINK_ENABLE_COROUTINE
147 #define VLINK_ENABLE_COROUTINE
148 #endif
149 #endif
150 #endif
151 
152 #ifdef VLINK_ENABLE_COROUTINE
153 
154 #include <atomic>
155 #include <chrono>
156 #include <coroutine>
157 #include <cstdint>
158 #include <exception>
159 #include <future>
160 #include <memory>
161 #include <mutex>
162 #include <optional>
163 #include <stdexcept>
164 #include <type_traits>
165 #include <utility>
166 #include <vector>
167 
168 #include "./exception.h"
169 #include "./functional.h"
170 #include "./graph_task.h"
171 #include "./macros.h"
172 #include "./memory_resource.h"
173 #include "./message_loop.h"
174 #include "./schedule.h"
175 
176 namespace vlink {
177 
178 /**
179  * @namespace vlink::Coroutine
180  * @brief Container namespace for the VLink coroutine integration layer.
181  *
182  * @details
183  * Holds the @c Task template, every awaiter, the @c co_spawn entry points and the orchestrators
184  * (@c when_all / @c when_any / @c sequence). Aliased as @c vlink::Co.
185  */
186 namespace Coroutine { // NOLINT(readability-identifier-naming)
187 
188 template <typename TypeT = void>
189 class Task;
190 
191 /**
192  * @namespace vlink::Coroutine::detail
193  * @brief Internal helpers for the coroutine layer.
194  *
195  * @details
196  * Hosts promise types, the detached-task adapter, the @c ResumePostResult enum, the awaiter
197  * shared state and the helpers that bridge coroutine handles back onto @c MessageLoop. Not part
198  * of the public API surface.
199  */
200 namespace detail {
201 
202 template <typename TypeT>
203 struct TaskPromise;
204 
205 /**
206  * @brief Allocates a coroutine frame through the process-wide @c MemoryPool.
207  *
208  * @param size Frame size requested by the compiler.
209  * @return Pointer to the freshly allocated frame.
210  * @throws std::bad_alloc when the underlying pool is exhausted.
211  */
212 VLINK_EXPORT void* allocate_frame(size_t size);
213 
214 /**
215  * @brief Returns a coroutine frame to the process-wide @c MemoryPool.
216  *
217  * @param ptr Frame previously obtained from @c allocate_frame. @c nullptr is a no-op.
218  * @param size Original frame size; must match the @c allocate_frame call.
219  */
220 VLINK_EXPORT void deallocate_frame(void* ptr, size_t size) noexcept;
221 
222 /**
223  * @struct FinalAwaiter
224  * @brief Final-suspend awaiter for @c Task promises; performs symmetric transfer.
225  *
226  * @details
227  * On final suspension the promise hands its stored continuation back to the dispatcher so the
228  * outer coroutine resumes immediately. When no continuation is set (the @c Task was never
229  * awaited) the awaiter returns @c std::noop_coroutine and the dispatcher unwinds normally.
230  */
231 struct FinalAwaiter final {
232  /**
233  * @brief Always returns @c false; the final suspension is unconditional.
234  *
235  * @return @c false.
236  */
237  // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
238  bool await_ready() const noexcept;
239 
240  /**
241  * @brief Returns the parent coroutine handle for symmetric transfer.
242  *
243  * @tparam PromiseT Promise type of the finishing coroutine.
244  * @param handle Handle to the finishing coroutine; its promise carries
245  * the @c continuation to resume.
246  * @return The stored continuation, or @c std::noop_coroutine() if none.
247  */
248  template <typename PromiseT>
249  std::coroutine_handle<> await_suspend(std::coroutine_handle<PromiseT> handle) noexcept;
250 
251  /**
252  * @brief No-op resume; the final awaiter never produces a value.
253  */
254  // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
255  void await_resume() const noexcept;
256 };
257 
258 /**
259  * @struct TaskPromiseBase
260  * @brief Shared storage and suspension hooks reused by every @c Task promise specialisation.
261  *
262  * @details
263  * Holds the parent continuation handle resumed at final suspension and an
264  * @c std::exception_ptr capturing any unhandled exception thrown by the coroutine body.
265  *
266  * @tparam TypeT Result type of the owning @c Task.
267  */
268 template <typename TypeT>
269 struct TaskPromiseBase {
270  std::coroutine_handle<> continuation; ///< Awaiter coroutine to resume on final suspension.
271  std::exception_ptr exception; ///< Captured unhandled exception, if any.
272 
273  /**
274  * @brief Initial-suspend hook; always suspends so the task starts lazily.
275  *
276  * @return @c std::suspend_always.
277  */
278  std::suspend_always initial_suspend() noexcept;
279 
280  /**
281  * @brief Final-suspend hook; returns a @c FinalAwaiter for symmetric transfer.
282  *
283  * @return @c FinalAwaiter instance bound to this promise.
284  */
285  FinalAwaiter final_suspend() noexcept;
286 
287  /**
288  * @brief Captures the currently active exception into the @c exception slot.
289  */
290  void unhandled_exception() noexcept;
291 };
292 
293 /**
294  * @struct TaskPromise
295  * @brief Promise type for value-returning @c Task<TypeT>.
296  *
297  * @details
298  * Allocates frames from the global @c MemoryPool and stores the @c co_return value in
299  * @c result so @c Task::await_resume can consume it.
300  *
301  * @tparam TypeT Result type produced by the coroutine body.
302  */
303 template <typename TypeT>
304 struct TaskPromise final : TaskPromiseBase<TypeT> {
305  std::optional<TypeT> result; ///< Storage for the @c co_return value.
306 
307  /**
308  * @brief Allocates the coroutine frame from the global memory pool.
309  *
310  * @param size Frame size requested by the compiler.
311  * @return Pointer to the allocated frame.
312  */
313  static void* operator new(size_t size);
314 
315  /**
316  * @brief Returns the coroutine frame to the global memory pool.
317  *
318  * @param ptr Frame previously allocated by @c operator @c new.
319  * @param size Original frame size.
320  */
321  static void operator delete(void* ptr, size_t size) noexcept;
322 
323  /**
324  * @brief Builds the @c Task object that owns this coroutine.
325  *
326  * @return @c Task<TypeT> wrapping the handle for this promise.
327  */
328  Task<TypeT> get_return_object() noexcept;
329 
330  /**
331  * @brief Captures the @c co_return value into @c result.
332  *
333  * @tparam UpT Forwarded value type.
334  * @param v Value produced by @c co_return.
335  */
336  template <typename UpT>
337  void return_value(UpT&& v) noexcept(std::is_nothrow_constructible_v<TypeT, UpT&&>);
338 };
339 
340 /**
341  * @struct TaskPromise<void>
342  * @brief Specialisation of @c TaskPromise for @c Task<void>.
343  *
344  * @details
345  * Carries no result slot; @c return_void is a no-op aside from satisfying the
346  * coroutine promise contract.
347  */
348 template <>
349 struct TaskPromise<void> final : TaskPromiseBase<void> {
350  /**
351  * @brief Allocates the coroutine frame from the global memory pool.
352  *
353  * @param size Frame size requested by the compiler.
354  * @return Pointer to the allocated frame.
355  */
356  static void* operator new(size_t size);
357 
358  /**
359  * @brief Returns the coroutine frame to the global memory pool.
360  *
361  * @param ptr Frame previously allocated by @c operator @c new.
362  * @param size Original frame size.
363  */
364  static void operator delete(void* ptr, size_t size) noexcept;
365 
366  /**
367  * @brief Builds the @c Task<void> that owns this coroutine.
368  *
369  * @return @c Task<void> wrapping the handle for this promise.
370  */
371  Task<void> get_return_object() noexcept;
372 
373  /**
374  * @brief No-op @c co_return for void tasks.
375  */
376  void return_void() noexcept;
377 };
378 
379 /**
380  * @struct DetachedTask
381  * @brief Fire-and-forget coroutine wrapper used internally by @c co_spawn.
382  *
383  * @details
384  * Holds a @c std::coroutine_handle for a coroutine whose frame is owned by the
385  * task itself: the promise type does not suspend at the final point and the
386  * frame is destroyed automatically when the body completes. Exceptions thrown
387  * by the inner coroutine are caught and logged at error level so that a stray
388  * throw cannot tear down the owning @c MessageLoop.
389  */
390 struct VLINK_EXPORT DetachedTask final {
391  /**
392  * @struct promise_type
393  * @brief Promise type that powers @c DetachedTask coroutines.
394  *
395  * @details
396  * Frames are allocated through the global @c MemoryPool. The coroutine
397  * suspends initially (so the caller can decide where to resume it) and
398  * never suspends at the final point (the frame self-destructs).
399  */
400  struct VLINK_EXPORT promise_type final { // NOLINT(readability-identifier-naming)
401  /**
402  * @brief Allocates the coroutine frame from the global memory pool.
403  *
404  * @param size Frame size requested by the compiler.
405  * @return Pointer to the allocated frame.
406  */
407  static void* operator new(size_t size);
408 
409  /**
410  * @brief Returns the coroutine frame to the global memory pool.
411  *
412  * @param ptr Frame previously allocated by @c operator @c new.
413  * @param size Original frame size.
414  */
415  static void operator delete(void* ptr, size_t size) noexcept;
416 
417  /**
418  * @brief Builds the @c DetachedTask wrapper that holds this promise's handle.
419  *
420  * @return @c DetachedTask wrapping the new coroutine handle.
421  */
422  DetachedTask get_return_object() noexcept;
423 
424  /**
425  * @brief Initial suspension; the caller decides when to resume.
426  *
427  * @return @c std::suspend_always.
428  */
429  std::suspend_always initial_suspend() noexcept;
430 
431  /**
432  * @brief Final suspension; never suspends so the frame self-destructs.
433  *
434  * @return @c std::suspend_never.
435  */
436  std::suspend_never final_suspend() noexcept;
437 
438  /**
439  * @brief No-op @c co_return for detached coroutines.
440  */
441  void return_void() noexcept;
442 
443  /**
444  * @brief Catches and logs unhandled exceptions thrown by the body.
445  *
446  * @details
447  * Exceptions are intentionally swallowed; the detached frame must not
448  * propagate failures back into the owning @c MessageLoop.
449  */
450  void unhandled_exception() noexcept;
451  };
452 
453  using Handle = std::coroutine_handle<promise_type>;
454 
455  /**
456  * @brief Constructs an empty detached task with no associated frame.
457  */
458  DetachedTask() noexcept;
459 
460  /**
461  * @brief Destroys the wrapper only; the frame is never destroyed here.
462  *
463  * @details
464  * This type is a plain handle carrier, not an owning RAII wrapper. The coroutine suspends
465  * initially and self-destructs at its final suspend point, so a resumed frame releases
466  * itself whenever it completes, possibly after the wrapper is gone; only a frame that was
467  * never resumed has to be released by the caller through @c handle.destroy(). Destroying
468  * it here would double-free the common case.
469  */
470  ~DetachedTask();
471 
472  /**
473  * @brief Constructs a detached task holding @p h.
474  *
475  * @param h Coroutine handle to carry.
476  */
477  explicit DetachedTask(Handle h) noexcept;
478 
479  /**
480  * @brief Move-constructs a detached task, transferring the handle.
481  *
482  * @param other Source task; left empty after the move.
483  */
484  DetachedTask(DetachedTask&& other) noexcept;
485 
486  /**
487  * @brief Move-assigns a detached task, transferring the handle.
488  *
489  * @details
490  * The handle previously carried is overwritten, not destroyed, matching the non-owning
491  * contract above; release it beforehand when it names a frame that was never resumed.
492  *
493  * @param other Source task; left empty after the move.
494  * @return Reference to @c *this.
495  */
496  DetachedTask& operator=(DetachedTask&& other) noexcept;
497 
498  Handle handle; ///< Coroutine handle; @c {} when the task has been released.
499 
500  VLINK_DISALLOW_COPY_AND_ASSIGN(DetachedTask)
501 };
502 
503 /**
504  * @brief Bridges a @c Task<void> into a @c DetachedTask coroutine.
505  *
506  * @param task Task to await inside the detached coroutine.
507  * @return @c DetachedTask carrying the handle of the new frame.
508  */
509 VLINK_EXPORT DetachedTask co_spawn_void_impl(Task<void> task);
510 
511 /**
512  * @brief Bridges a value-returning @c Task<TypeT> with a completion callback.
513  *
514  * @tparam TypeT Result type produced by the inner task.
515  * @tparam CallbackT Callable invoked with the task's result on success.
516  * @param task Inner task to await.
517  * @param on_complete Callback invoked on the loop thread on successful completion.
518  * @return @c DetachedTask carrying the handle of the new frame.
519  */
520 template <typename TypeT, typename CallbackT>
521 DetachedTask co_spawn_value_impl(Task<TypeT> task, CallbackT on_complete);
522 
523 /**
524  * @brief Bridges a @c Task<void> with a completion callback.
525  *
526  * @tparam CallbackT Callable invoked after the inner task completes.
527  * @param task Inner task to await.
528  * @param on_complete Callback invoked on the loop thread on successful completion.
529  * @return @c DetachedTask carrying the handle of the new frame.
530  */
531 template <typename CallbackT>
532 DetachedTask co_spawn_void_with_cb_impl(Task<void> task, CallbackT on_complete);
533 
534 /**
535  * @enum ResumePostResult
536  * @brief Outcome of attempting to post a coroutine resume back onto a loop.
537  *
538  * @details
539  * Returned by @c post_callback_if_alive (and by the awaiter helpers built on
540  * it). Drives the retry logic in @c ScheduleAwaiter, @c YieldAwaiter,
541  * @c DelayAwaiter, @c FutureAwaiter and @c GraphAwaiter.
542  */
543 enum class ResumePostResult : uint8_t {
544  kPosted = 0, ///< Resume callback was accepted by the target loop's queue.
545  kRetry, ///< Target loop is alive but currently full; caller should retry later.
546  kClosed, ///< Target loop has been (or is about to be) quit; resume cannot be delivered.
547 };
548 
549 struct AwaiterResumeState;
550 
551 /**
552  * @brief Maximum number of @c kRetry passes before a queued resume is reported as failed.
553  *
554  * @details
555  * Each retry tick is approximately 1 ms (the @c FutureWaitLoop poll cadence),
556  * giving a total bound of roughly 30 seconds before the awaiter converts a
557  * stuck retry sequence into either an @c OperationCancelled or an
558  * @c std::runtime_error, depending on the awaiter type.
559  */
560 inline constexpr uint32_t kMaxResumePostRetry = 30000U;
561 
562 /**
563  * @brief Posts a callback onto @p loop while honouring the alive-state gate.
564  *
565  * @details
566  * If @p loop or @p alive_state is null, or if the loop has been signalled to
567  * quit, @p drop_callback is invoked and @c ResumePostResult::kClosed is
568  * returned. Otherwise the function takes @p alive_state's mutex briefly and
569  * attempts to post @p resume_callback under @c TaskOverflowPolicy::kReject; on
570  * success it returns @c kPosted, on a full queue it returns @c kRetry without
571  * having held the mutex across any sleep. On @c kPriorityType loops the
572  * @c MessageLoop::kNoPriority value is remapped to
573  * @c MessageLoop::kNormalPriority so default-priority coroutines do not sink to
574  * the bottom of the priority queue.
575  *
576  * @param loop Target loop to post onto.
577  * @param alive_state Loop's alive-state gate; obtained via @c MessageLoop::get_alive_state.
578  * @param resume_callback Callable invoked on the loop thread on success.
579  * @param drop_callback Callable invoked when the loop is closed or the task is dropped.
580  * @param priority Schedule priority; honoured only on @c kPriorityType loops.
581  * @return One of @c kPosted, @c kRetry, @c kClosed.
582  */
583 VLINK_EXPORT ResumePostResult post_callback_if_alive(MessageLoop* loop,
584  const std::shared_ptr<MessageLoop::AliveState>& alive_state,
585  MoveFunction<void()>&& resume_callback,
586  MoveFunction<void()>&& drop_callback, uint16_t priority = 0);
587 
588 /**
589  * @brief Posts the initial resume of a detached coroutine onto @p loop.
590  *
591  * @details
592  * Used by the top-level @c co_spawn entry points. If the loop is already
593  * closed or its queue cannot accept the resume after @c kMaxResumePostRetry
594  * attempts, the handle is destroyed instead of being resumed.
595  *
596  * @param loop Target loop on which the coroutine should start running.
597  * @param handle Detached coroutine handle taking ownership of the frame.
598  * @param priority Schedule priority; honoured only on @c kPriorityType loops.
599  */
600 VLINK_EXPORT void co_spawn_detached_handle(MessageLoop& loop, DetachedTask::Handle handle, uint16_t priority = 0);
601 
602 /**
603  * @brief Enqueues a poll closure on the shared @c FutureWaitLoop helper thread.
604  *
605  * @details
606  * The closure is invoked repeatedly at the helper's poll cadence (~1 ms). It
607  * returns @c true when it has finished and may be removed from the queue, or
608  * @c false to be re-polled on the next pass.
609  *
610  * @param poll Poll closure registered with the helper thread.
611  */
612 VLINK_EXPORT void register_future_wait(MoveFunction<bool()>&& poll);
613 
614 /**
615  * @brief Submits deferred future execution to the shared worker pool.
616  *
617  * @param callback Calls @c wait() on the owned deferred future.
618  * @return @c false if the worker pool cannot accept the task.
619  */
620 [[nodiscard]] VLINK_EXPORT bool run_deferred_future(MoveFunction<void()>&& callback);
621 
622 } // namespace detail
623 
624 /**
625  * @class Task
626  * @brief Coroutine return type; lazily started, awaitable from another coroutine.
627  *
628  * @details
629  * The coroutine body does not run until the @c Task is either awaited from
630  * another coroutine or passed to @c co_spawn(). Moving the @c Task transfers
631  * ownership; destroying a still-suspended @c Task destroys its coroutine frame.
632  *
633  * @tparam TypeT Result type produced by @c co_return. Use @c void for tasks
634  * that produce no value.
635  */
636 template <typename TypeT>
637 class Task final {
638  public:
639  using promise_type = detail::TaskPromise<TypeT>;
640  using Handle = std::coroutine_handle<promise_type>;
641 
642  /**
643  * @brief Constructs an empty @c Task that does not own a coroutine frame.
644  */
645  Task() noexcept = default;
646 
647  /**
648  * @brief Constructs a @c Task that takes ownership of @p handle.
649  *
650  * @param handle Coroutine handle produced by @c TaskPromise::get_return_object.
651  */
652  explicit Task(Handle handle) noexcept;
653 
654  /**
655  * @brief Move-constructs a @c Task, transferring frame ownership.
656  *
657  * @param other Source task; left empty after the move.
658  */
659  Task(Task&& other) noexcept;
660 
661  /**
662  * @brief Move-assigns a @c Task, destroying any previously owned frame.
663  *
664  * @param other Source task; left empty after the move.
665  * @return Reference to @c *this.
666  */
667  Task& operator=(Task&& other) noexcept;
668 
669  /**
670  * @brief Destroys the owned coroutine frame, if any.
671  */
672  ~Task();
673 
674  /**
675  * @brief Tests whether this task owns a coroutine frame.
676  *
677  * @return @c true if the task is non-empty.
678  */
679  [[nodiscard]] bool valid() const noexcept;
680 
681  /**
682  * @brief Tests whether the owned frame has finished executing.
683  *
684  * @return @c true if the task is valid and the coroutine has run to completion.
685  */
686  [[nodiscard]] bool done() const noexcept;
687 
688  /**
689  * @brief Coroutine awaiter readiness hook.
690  *
691  * @return @c true if the task is empty or already done; otherwise @c false.
692  */
693  bool await_ready() const noexcept;
694 
695  /**
696  * @brief Coroutine awaiter suspension hook; performs symmetric transfer.
697  *
698  * @param awaiter Coroutine handle awaiting this task's completion.
699  * @return The handle of the inner coroutine to resume.
700  */
701  std::coroutine_handle<> await_suspend(std::coroutine_handle<> awaiter) noexcept;
702 
703  /**
704  * @brief Coroutine awaiter resume hook; extracts the result or rethrows.
705  *
706  * @details
707  * Throws @c std::logic_error when called on an invalid task. If the inner
708  * coroutine captured an unhandled exception, it is rethrown here.
709  *
710  * @return The value stored by @c co_return for non-void tasks.
711  */
712  TypeT await_resume();
713 
714  /**
715  * @brief Releases ownership of the underlying coroutine handle.
716  *
717  * @return Handle owned by this task; the task is empty after the call.
718  */
719  Handle release() noexcept;
720 
721  /**
722  * @brief Returns the underlying coroutine handle without releasing ownership.
723  *
724  * @return Current coroutine handle (may be @c {} for an empty task).
725  */
726  [[nodiscard]] Handle native_handle() const noexcept;
727 
728  private:
729  Handle handle_;
730 
732 };
733 
734 /**
735  * @struct ScheduleAwaiter
736  * @brief Awaiter that resumes the coroutine on @p loop's worker thread.
737  *
738  * @details
739  * Built on top of @c detail::post_callback_if_alive. After @c co_await
740  * @c schedule(loop), the remainder of the coroutine runs on @p loop's thread.
741  * If the target loop's queue is currently full, the awaiter retries via the
742  * shared @c FutureWaitLoop helper at a ~1 ms cadence, up to
743  * @c detail::kMaxResumePostRetry attempts.
744  *
745  * @warning If @p loop is already quitting or retries are exhausted,
746  * @c await_resume() throws @c std::runtime_error. The failure resume
747  * is delivered on the @c FutureWaitLoop helper thread, not on the
748  * target loop thread.
749  */
750 struct VLINK_EXPORT ScheduleAwaiter final {
751  /**
752  * @brief Constructs an empty awaiter with no target loop.
753  */
754  ScheduleAwaiter() noexcept;
755 
756  /**
757  * @brief Constructs an awaiter bound to a target loop and resume state.
758  *
759  * @param loop Target loop on which to resume.
760  * @param alive_state Target loop's alive-state gate.
761  * @param state Shared awaiter resume state.
762  * @param priority Schedule priority for the resume.
763  */
764  ScheduleAwaiter(MessageLoop* loop, std::shared_ptr<MessageLoop::AliveState> alive_state,
765  std::shared_ptr<detail::AwaiterResumeState> state, uint16_t priority) noexcept;
766 
767  /**
768  * @brief Move-constructs the awaiter.
769  */
770  ScheduleAwaiter(ScheduleAwaiter&&) noexcept;
771 
772  /**
773  * @brief Move-assigns the awaiter.
774  */
775  ScheduleAwaiter& operator=(ScheduleAwaiter&&) noexcept;
776 
777  MessageLoop* loop{nullptr}; ///< Target loop on which to resume.
778  std::shared_ptr<MessageLoop::AliveState> alive_state; ///< Target loop's alive-state gate.
779  std::shared_ptr<detail::AwaiterResumeState> state; ///< Shared resume state holding the handle.
780  uint16_t priority{0}; ///< Schedule priority for the resume.
781  bool failed{false}; ///< Set to @c true if posting ultimately failed.
782 
783  /**
784  * @brief Awaiter readiness hook.
785  *
786  * @return Always @c false; the hop must be posted asynchronously.
787  */
788  static bool await_ready() noexcept;
789 
790  /**
791  * @brief Destructor; abandons any pending retry registered on the helper thread.
792  */
793  ~ScheduleAwaiter();
794 
795  /**
796  * @brief Posts the coroutine resume onto the target loop.
797  *
798  * @details
799  * On @c kRetry the awaiter registers a retry closure on the shared
800  * @c FutureWaitLoop helper; on @c kClosed the @c failed flag is raised so
801  * that @c await_resume can throw.
802  *
803  * @param handle Coroutine handle to resume on success.
804  * @return @c true; the awaiter always stays suspended until a resume fires.
805  */
806  bool await_suspend(std::coroutine_handle<> handle);
807 
808  /**
809  * @brief Verifies that the hop succeeded.
810  *
811  * @throws std::runtime_error if the target loop closed or retries were exhausted.
812  */
813  void await_resume();
814 
815  VLINK_DISALLOW_COPY_AND_ASSIGN(ScheduleAwaiter)
816 };
817 
818 /**
819  * @struct YieldAwaiter
820  * @brief Awaiter that re-posts the coroutine to the back of @p loop's queue.
821  *
822  * @details
823  * Useful for cooperative yielding inside a long-running coroutine running on
824  * the loop thread, allowing other queued tasks a chance to execute. Built on
825  * top of the same @c post_callback_if_alive machinery as @c ScheduleAwaiter.
826  *
827  * @warning If @p loop is already quitting or retries are exhausted,
828  * @c await_resume() throws @c std::runtime_error. The failure resume
829  * is delivered on the @c FutureWaitLoop helper thread.
830  */
831 struct VLINK_EXPORT YieldAwaiter final {
832  /**
833  * @brief Constructs an empty awaiter with no target loop.
834  */
835  YieldAwaiter() noexcept;
836 
837  /**
838  * @brief Constructs an awaiter bound to a target loop and resume state.
839  *
840  * @param loop Target loop on which to re-post.
841  * @param alive_state Target loop's alive-state gate.
842  * @param state Shared awaiter resume state.
843  * @param priority Schedule priority for the re-post.
844  */
845  YieldAwaiter(MessageLoop* loop, std::shared_ptr<MessageLoop::AliveState> alive_state,
846  std::shared_ptr<detail::AwaiterResumeState> state, uint16_t priority) noexcept;
847 
848  /**
849  * @brief Move-constructs the awaiter.
850  */
851  YieldAwaiter(YieldAwaiter&&) noexcept;
852 
853  /**
854  * @brief Move-assigns the awaiter.
855  */
856  YieldAwaiter& operator=(YieldAwaiter&&) noexcept;
857 
858  MessageLoop* loop{nullptr}; ///< Target loop to re-post onto.
859  std::shared_ptr<MessageLoop::AliveState> alive_state; ///< Target loop's alive-state gate.
860  std::shared_ptr<detail::AwaiterResumeState> state; ///< Shared resume state holding the handle.
861  uint16_t priority{0}; ///< Schedule priority for the re-post.
862  bool failed{false}; ///< Set to @c true if posting ultimately failed.
863 
864  /**
865  * @brief Awaiter readiness hook.
866  *
867  * @return Always @c false; the yield must complete a queue round-trip.
868  */
869  static bool await_ready() noexcept;
870 
871  /**
872  * @brief Destructor; abandons any pending retry registered on the helper thread.
873  */
874  ~YieldAwaiter();
875 
876  /**
877  * @brief Re-posts the coroutine resume onto the target loop.
878  *
879  * @param handle Coroutine handle to resume on success.
880  * @return @c true; the awaiter always stays suspended until a resume fires.
881  */
882  bool await_suspend(std::coroutine_handle<> handle);
883 
884  /**
885  * @brief Verifies that the yield round-trip succeeded.
886  *
887  * @throws std::runtime_error if the target loop closed or retries were exhausted.
888  */
889  void await_resume();
890 
891  VLINK_DISALLOW_COPY_AND_ASSIGN(YieldAwaiter)
892 };
893 
894 /**
895  * @struct DelayAwaiter
896  * @brief Awaiter that suspends the coroutine for @p ms milliseconds.
897  *
898  * @details
899  * On success the coroutine resumes on @p loop's thread, even for @p ms == 0.
900  * Delay completion is observed by the shared @c FutureWaitLoop helper thread
901  * at a ~1 ms polling cadence. When the deadline is reached the awaiter posts
902  * its resume through @c post_callback_if_alive; full-queue conditions retry up
903  * to @c detail::kMaxResumePostRetry times before failing.
904  *
905  * @warning If @p loop is already quitting or retries are exhausted,
906  * @c await_resume() throws @c std::runtime_error. The failure resume
907  * is delivered on the @c FutureWaitLoop helper thread.
908  */
909 struct VLINK_EXPORT DelayAwaiter final {
910  /**
911  * @brief Constructs an empty awaiter with no target loop.
912  */
913  DelayAwaiter() noexcept;
914 
915  /**
916  * @brief Constructs an awaiter bound to a target loop and delay.
917  *
918  * @param loop Target loop on which to resume.
919  * @param alive_state Target loop's alive-state gate.
920  * @param state Shared awaiter resume state.
921  * @param ms Delay in milliseconds before the resume is posted.
922  * @param priority Schedule priority for the resume.
923  */
924  DelayAwaiter(MessageLoop* loop, std::shared_ptr<MessageLoop::AliveState> alive_state,
925  std::shared_ptr<detail::AwaiterResumeState> state, uint32_t ms, uint16_t priority) noexcept;
926 
927  /**
928  * @brief Move-constructs the awaiter.
929  */
930  DelayAwaiter(DelayAwaiter&&) noexcept;
931 
932  /**
933  * @brief Move-assigns the awaiter.
934  */
935  DelayAwaiter& operator=(DelayAwaiter&&) noexcept;
936 
937  MessageLoop* loop{nullptr}; ///< Target loop to resume on.
938  std::shared_ptr<MessageLoop::AliveState> alive_state; ///< Target loop's alive-state gate.
939  std::shared_ptr<detail::AwaiterResumeState> state; ///< Shared resume state holding the handle.
940  uint32_t ms{0}; ///< Delay in milliseconds.
941  uint16_t priority{0}; ///< Schedule priority for the resume.
942  bool failed{false}; ///< Set to @c true if scheduling failed.
943 
944  /**
945  * @brief Awaiter readiness hook.
946  *
947  * @return Always @c false; the delay must elapse asynchronously.
948  */
949  static bool await_ready() noexcept;
950 
951  /**
952  * @brief Destructor; abandons any pending retry registered on the helper thread.
953  */
954  ~DelayAwaiter();
955 
956  /**
957  * @brief Registers the delayed resume on the shared @c FutureWaitLoop helper.
958  *
959  * @param handle Coroutine handle to resume once the delay has elapsed.
960  * @return @c true; the awaiter always stays suspended until a resume fires.
961  */
962  bool await_suspend(std::coroutine_handle<> handle);
963 
964  /**
965  * @brief Verifies that the delay completed and the resume was posted.
966  *
967  * @throws std::runtime_error if the target loop closed or retries were exhausted.
968  */
969  void await_resume();
970 
971  VLINK_DISALLOW_COPY_AND_ASSIGN(DelayAwaiter)
972 };
973 
974 /**
975  * @class FutureAwaiter
976  * @brief Awaiter that suspends until a @c std::future becomes ready.
977  *
978  * @details
979  * Backed by the process-wide @c FutureWaitLoop helper thread (see
980  * @c detail::register_future_wait). A single long-lived helper thread services
981  * all pending @c await_future calls: it polls each registered future at a
982  * ~1 ms cadence using a non-blocking @c wait_for(0) and posts the resume back
983  * to @p loop as soon as the future is ready. The future is held in shared
984  * waiter state so a destroyed awaiter can retire the pending poll without
985  * leaving a dangling frame pointer in the helper thread.
986  *
987  * Deferred futures execute on a shared worker pool before their completion is
988  * posted back to the target loop.
989  *
990  * @note No per-await thread is spawned. Resume latency is bounded by the
991  * helper's ~1 ms cadence plus the target loop's task dispatch delay.
992  *
993  * @warning If @p loop is closed before the ready future can be posted back,
994  * the coroutine resumes on the helper thread and @c await_resume()
995  * throws @c OperationCancelled. On the normal path, exceptions
996  * stored in the future propagate via @c future.get().
997  *
998  * @tparam TypeT Result type produced by the awaited future.
999  */
1000 template <typename TypeT>
1001 class FutureAwaiter final {
1002  public:
1003  /**
1004  * @brief Constructs an awaiter that bridges @p fut into the coroutine layer.
1005  *
1006  * @param loop Target loop on which to resume once @p fut is ready.
1007  * @param fut Future to await; ownership is transferred into the awaiter.
1008  */
1009  FutureAwaiter(MessageLoop* loop, std::future<TypeT> fut) noexcept;
1010 
1011  /**
1012  * @brief Move-constructs the awaiter.
1013  */
1014  FutureAwaiter(FutureAwaiter&&) noexcept = default;
1015 
1016  /**
1017  * @brief Move-assigns the awaiter.
1018  */
1019  FutureAwaiter& operator=(FutureAwaiter&&) noexcept = default;
1020 
1021  /**
1022  * @brief Destructor; abandons the pending helper poll.
1023  */
1024  ~FutureAwaiter();
1025 
1026  /**
1027  * @brief Short-circuits when the future is already in a ready state.
1028  *
1029  * @return @c true if the future is ready or invalid; otherwise @c false.
1030  */
1031  bool await_ready() const noexcept;
1032 
1033  /**
1034  * @brief Registers a poll closure on the shared @c FutureWaitLoop helper.
1035  *
1036  * @param handle Coroutine handle to resume once the future is ready.
1037  * @throws std::runtime_error if deferred execution cannot be submitted to the worker pool.
1038  */
1039  void await_suspend(std::coroutine_handle<> handle);
1040 
1041  /**
1042  * @brief Extracts the value from the future or rethrows its exception.
1043  *
1044  * @return Future result for non-void instantiations.
1045  * @throws OperationCancelled if the target loop closed before the resume could be posted.
1046  * @note Exceptions stored in the future are rethrown by @c future.get().
1047  */
1048  TypeT await_resume();
1049 
1050  private:
1051  struct State;
1052 
1053  MessageLoop* loop_{nullptr};
1054  std::shared_ptr<State> state_;
1055 
1056  VLINK_DISALLOW_COPY_AND_ASSIGN(FutureAwaiter)
1057 };
1058 
1059 /**
1060  * @class GraphAwaiter
1061  * @brief Awaiter that suspends until a @c GraphTask reaches @c kStatusDone.
1062  *
1063  * @details
1064  * Installs a single-shot status callback on the graph; on @c kStatusDone the
1065  * coroutine resume is posted back onto @p loop. If the graph is already done
1066  * at the await point, @c await_ready returns @c true and no callback is
1067  * registered. Cancelled or never-started graphs leave the coroutine suspended
1068  * indefinitely; the caller must ensure the graph eventually runs. The status
1069  * subscription is unregistered automatically once the awaiter resumes, so
1070  * multiple coroutines awaiting the same graph are safe.
1071  *
1072  * @warning If @p loop closes after the graph becomes done but before the resume
1073  * can be posted, @c await_resume() throws @c OperationCancelled. The
1074  * failure resume is delivered on the @c FutureWaitLoop helper thread,
1075  * not on the target loop thread.
1076  */
1077 class VLINK_EXPORT GraphAwaiter final {
1078  public:
1079  /**
1080  * @brief Constructs an awaiter that monitors @p graph for completion.
1081  *
1082  * @param loop Loop on which to resume the coroutine.
1083  * @param graph Graph task to monitor.
1084  */
1085  GraphAwaiter(MessageLoop* loop, GraphTaskPtr graph) noexcept;
1086 
1087  /**
1088  * @brief Move-constructs the awaiter.
1089  */
1090  GraphAwaiter(GraphAwaiter&&) noexcept;
1091 
1092  /**
1093  * @brief Move-assigns the awaiter.
1094  */
1095  GraphAwaiter& operator=(GraphAwaiter&&) noexcept;
1096 
1097  /**
1098  * @brief Destructor; unregisters the status callback and abandons any pending resume.
1099  */
1100  ~GraphAwaiter();
1101 
1102  /**
1103  * @brief Short-circuits when the graph is empty or already complete.
1104  *
1105  * @return @c true if @c graph_ is null or already @c kStatusDone.
1106  */
1107  [[nodiscard]] bool await_ready() const noexcept;
1108 
1109  /**
1110  * @brief Registers a single-shot status callback waiting for @c kStatusDone.
1111  *
1112  * @param handle Coroutine handle to resume on completion.
1113  */
1114  void await_suspend(std::coroutine_handle<> handle);
1115 
1116  /**
1117  * @brief Verifies that the resume reached the target loop.
1118  *
1119  * @throws OperationCancelled if the target loop closed before the resume could be posted.
1120  */
1121  void await_resume() const;
1122 
1123  private:
1124  struct State;
1125 
1126  MessageLoop* loop_{nullptr};
1127  GraphTaskPtr graph_;
1128  std::shared_ptr<State> state_;
1129 
1130  VLINK_DISALLOW_COPY_AND_ASSIGN(GraphAwaiter)
1131 };
1132 
1133 /**
1134  * @brief Returns an awaiter that hops the coroutine onto @p loop's thread.
1135  *
1136  * @details
1137  * Use @c co_await @c schedule(loop) to migrate the remainder of a coroutine to
1138  * @p loop's thread. On @c kPriorityType loops the @c MessageLoop::kNoPriority
1139  * sentinel is internally remapped to @c MessageLoop::kNormalPriority so default
1140  * coroutines do not sink to the bottom of the queue.
1141  *
1142  * @param loop Target loop to resume on.
1143  * @param priority Schedule priority. Values come from @c MessageLoop::Priority
1144  * (@c kNoPriority is FIFO, @c kNormalPriority is 100, etc.).
1145  * Honoured only on @c kPriorityType loops.
1146  * @return @c ScheduleAwaiter ready to be @c co_await-ed.
1147  */
1148 VLINK_EXPORT ScheduleAwaiter schedule(MessageLoop& loop, uint16_t priority = MessageLoop::kNoPriority) noexcept;
1149 
1150 /**
1151  * @brief Returns an awaiter that yields once back to @p loop's queue.
1152  *
1153  * @param loop Loop owning the coroutine.
1154  * @param priority Re-post priority from @c MessageLoop::Priority; honoured only
1155  * on @c kPriorityType loops.
1156  * @return @c YieldAwaiter ready to be @c co_await-ed.
1157  */
1158 VLINK_EXPORT YieldAwaiter yield(MessageLoop& loop, uint16_t priority = MessageLoop::kNoPriority) noexcept;
1159 
1160 /**
1161  * @brief Returns an awaiter that suspends for @p ms milliseconds.
1162  *
1163  * @param loop Loop on which the coroutine resumes after the delay.
1164  * @param ms Delay in milliseconds. Zero is allowed and still produces a
1165  * resume hop through the helper thread.
1166  * @param priority Resume priority from @c MessageLoop::Priority; honoured only
1167  * on @c kPriorityType loops.
1168  * @return @c DelayAwaiter ready to be @c co_await-ed.
1169  */
1170 VLINK_EXPORT DelayAwaiter delay_ms(MessageLoop& loop, uint32_t ms,
1171  uint16_t priority = MessageLoop::kNoPriority) noexcept;
1172 
1173 /**
1174  * @brief Returns an awaiter that suspends until @p fut is ready, resuming on @p loop.
1175  *
1176  * @tparam TypeT Result type stored in the future.
1177  * @param loop Loop on which the coroutine resumes once @p fut is ready.
1178  * @param fut Future to await; ownership is transferred into the awaiter.
1179  * @return @c FutureAwaiter ready to be @c co_await-ed.
1180  */
1181 template <typename TypeT>
1182 FutureAwaiter<TypeT> await_future(MessageLoop& loop, std::future<TypeT> fut) noexcept;
1183 
1184 /**
1185  * @brief Schedules a top-level @c Task<void> on @p loop (fire-and-forget).
1186  *
1187  * @details
1188  * The coroutine begins executing on @p loop's thread. Ownership of the task
1189  * frame is transferred to an internal detached coroutine, which destroys itself
1190  * and the task frame once the body completes. Exceptions thrown from the task are caught by
1191  * @c DetachedTask::unhandled_exception, logged at error level and swallowed:
1192  * the loop continues running.
1193  *
1194  * @par Joining from synchronous code
1195  * Use the three-argument @c co_spawn overload with a callback to bridge to a
1196  * @c std::promise / @c std::future pair, then wait on the future:
1197  * @code
1198  * std::promise<void> p;
1199  * auto fut = p.get_future();
1200  * Co::co_spawn(loop, my_void_task(), [&p]() { p.set_value(); });
1201  * fut.wait();
1202  * @endcode
1203  *
1204  * @note If @c my_void_task throws, the callback is not invoked and @c fut
1205  * never becomes ready. Either catch inside @c my_void_task or use a
1206  * value-returning task that converts errors into a sentinel result.
1207  *
1208  * @param loop Loop on which the coroutine starts running.
1209  * @param task Task to spawn; ownership is transferred into the call.
1210  */
1211 VLINK_EXPORT void co_spawn(MessageLoop& loop, Task<void>&& task);
1212 
1213 /**
1214  * @brief Same as @c co_spawn, with an explicit dispatch priority.
1215  *
1216  * @param loop Loop on which the coroutine starts running.
1217  * @param task Task to spawn; ownership is transferred into the call.
1218  * @param priority Schedule priority; honoured only on @c kPriorityType loops.
1219  */
1220 VLINK_EXPORT void co_spawn_with_priority(MessageLoop& loop, Task<void>&& task, uint16_t priority);
1221 
1222 /**
1223  * @brief Schedules a top-level @c Task<TypeT> with a completion callback.
1224  *
1225  * @details
1226  * The coroutine begins executing on @p loop's thread. When the task completes
1227  * successfully, @p on_complete is invoked on the loop thread with the result.
1228  *
1229  * @warning Exceptions thrown by the task are swallowed: they are logged via
1230  * @c DetachedTask::unhandled_exception and @p on_complete is NOT
1231  * invoked. This API is unsuitable for code that must observe task
1232  * failure. To observe failure either:
1233  * - Catch inside the task body and convert to a sentinel result, or
1234  * - Use @c when_all / @c when_any / @c sequence, which capture the
1235  * original exception via the runner+guard machinery, or
1236  * - @c co_await the @c Task directly from a parent coroutine.
1237  *
1238  * @par Example
1239  * @code
1240  * auto pp = std::make_shared<std::promise<TypeT>>();
1241  * auto fut = pp->get_future();
1242  * Co::co_spawn(loop, task_that_may_throw(),
1243  * [pp](TypeT v) { pp->set_value(std::move(v)); });
1244  * try {
1245  * TypeT result = co_await Co::await_future(loop, std::move(fut));
1246  * } catch (...) {
1247  * // The future still does not see the original exception.
1248  * }
1249  * @endcode
1250  *
1251  * @tparam TypeT Result type produced by the task.
1252  * @tparam CallbackT Callable invoked with the task's result on success.
1253  * @param loop Loop on which the coroutine starts running.
1254  * @param task Task to spawn; ownership is transferred into the call.
1255  * @param on_complete Completion callback invoked on the loop thread on success.
1256  */
1257 template <typename TypeT, typename CallbackT,
1258  // NOLINTNEXTLINE(modernize-use-constraints)
1259  typename = std::enable_if_t<!std::is_integral_v<std::remove_reference_t<CallbackT>>>>
1260 void co_spawn(MessageLoop& loop, Task<TypeT>&& task, CallbackT&& on_complete);
1261 
1262 /**
1263  * @brief Same as the value-returning @c co_spawn, with an explicit dispatch priority.
1264  *
1265  * @tparam TypeT Result type produced by the task.
1266  * @tparam CallbackT Callable invoked with the task's result on success.
1267  * @param loop Loop on which the coroutine starts running.
1268  * @param task Task to spawn; ownership is transferred into the call.
1269  * @param on_complete Completion callback invoked on the loop thread on success.
1270  * @param priority Schedule priority; honoured only on @c kPriorityType loops.
1271  */
1272 template <typename TypeT, typename CallbackT,
1273  // NOLINTNEXTLINE(modernize-use-constraints)
1274  typename = std::enable_if_t<!std::is_integral_v<std::remove_reference_t<CallbackT>>>>
1275 void co_spawn_with_priority(MessageLoop& loop, Task<TypeT>&& task, CallbackT&& on_complete, uint16_t priority);
1276 
1277 /**
1278  * @brief Returns an awaiter that suspends until @p graph reaches @c kStatusDone.
1279  *
1280  * @param loop Loop on which to resume the coroutine.
1281  * @param graph Graph task to monitor; must be non-null.
1282  * @return @c GraphAwaiter ready to be @c co_await-ed.
1283  * @throws std::invalid_argument if @p graph is null.
1284  */
1285 VLINK_EXPORT GraphAwaiter await_graph(MessageLoop& loop, GraphTaskPtr graph);
1286 
1287 /**
1288  * @brief Coroutine wrapper around @c MessageLoop::exec_task.
1289  *
1290  * @details
1291  * Posts @p callback under the given @c Schedule::Config envelope and suspends
1292  * until the callback has run. Exceptions thrown by @p callback are stored in
1293  * an internal @c std::promise and rethrown from the awaiting @c co_await. If
1294  * the underlying @c exec_task post fails (queue full or loop closed), the
1295  * coroutine resumes with an @c std::runtime_error carrying a descriptive
1296  * message. If an accepted task is discarded, releasing its promise completes
1297  * the future with @c std::future_error; a closed target loop instead reports
1298  * @c OperationCancelled through the future awaiter.
1299  *
1300  * @tparam CallbackT Callable returning @c void.
1301  * @param loop Loop on which the callback is scheduled.
1302  * @param config Schedule envelope copied into the coroutine frame.
1303  * @param callback Callable owned by the coroutine frame until dispatch.
1304  * @return @c Task<void> that completes after @p callback returns.
1305  */
1306 template <typename CallbackT>
1307 Task<void> exec(MessageLoop& loop, Schedule::Config config, CallbackT callback);
1308 
1309 /**
1310  * @brief Awaits every @c Task<TypeT> in @p tasks and returns their results.
1311  *
1312  * @details
1313  * Each task is dispatched via @c co_spawn on @p loop. Results are stored in
1314  * the order of the input vector. @c when_all waits for every sub-task to
1315  * finish (success or failure) before completing. If any sub-task throws, the
1316  * first exception observed is rethrown from the awaiting @c co_await with its
1317  * original type preserved; subsequent exceptions from sibling tasks are
1318  * dropped. An invalid (moved-from or default-constructed) task fails with
1319  * @c std::logic_error like a throwing sub-task.
1320  *
1321  * @note @p TypeT must be default-constructible; the results vector is
1322  * pre-sized via @c std::vector<TypeT>(count).
1323  *
1324  * @tparam TypeT Result type produced by every sub-task.
1325  * @param loop Loop on which sub-tasks are spawned and the caller resumes.
1326  * @param tasks Sub-tasks to await; ownership is transferred into the call.
1327  * @return @c Task that resolves to a vector of results in input order.
1328  */
1329 template <typename TypeT>
1330 Task<std::vector<TypeT>> when_all(MessageLoop& loop, std::vector<Task<TypeT>> tasks);
1331 
1332 /**
1333  * @brief Awaits every @c Task<void> in @p tasks to complete.
1334  *
1335  * @details
1336  * Waits for every sub-task to finish. If any sub-task throws, the first
1337  * exception observed is rethrown from the awaiting @c co_await with its
1338  * original type preserved; subsequent exceptions are dropped. An invalid
1339  * task fails with @c std::logic_error like a throwing sub-task.
1340  *
1341  * @param loop Loop on which sub-tasks are spawned and the caller resumes.
1342  * @param tasks Sub-tasks to await; ownership is transferred into the call.
1343  * @return @c Task<void> that completes once every sub-task has finished.
1344  */
1345 VLINK_EXPORT Task<void> when_all(MessageLoop& loop, std::vector<Task<void>> tasks);
1346 
1347 /**
1348  * @brief Records the index and result of the first @c Task<TypeT> to complete successfully.
1349  *
1350  * @details
1351  * The winner (first successful completion) is selected by an atomic
1352  * compare-exchange; losing tasks continue running until completion and their
1353  * results are dropped. @c when_any does not return until every sub-task has
1354  * finished — this is required to avoid leaking orphaned sub-task frames, since
1355  * this layer offers no cross-coroutine cancellation. If "abandon losers"
1356  * semantics with bounded latency are required, each sub-task itself must
1357  * respect a deadline. If every sub-task throws, the first exception observed
1358  * is rethrown from the awaiting @c co_await; an invalid task counts as one
1359  * throwing @c std::logic_error.
1360  *
1361  * @tparam TypeT Result type produced by every sub-task.
1362  * @param loop Loop on which sub-tasks are spawned and the caller resumes.
1363  * @param tasks Sub-tasks to race; ownership is transferred into the call.
1364  * @return @c Task resolving to @c {winning_index, winning_result}.
1365  * @throws std::invalid_argument if @p tasks is empty; observed at the awaiting
1366  * @c co_await site (since @c when_any is itself a coroutine).
1367  */
1368 template <typename TypeT>
1369 Task<std::pair<size_t, TypeT>> when_any(MessageLoop& loop, std::vector<Task<TypeT>> tasks);
1370 
1371 /**
1372  * @brief Records the index of the first @c Task<void> to complete successfully.
1373  *
1374  * @details
1375  * The winner (first successful completion) is selected by an atomic
1376  * compare-exchange; losing tasks continue running until completion. @c when_any
1377  * does not return until every sub-task has finished — this is required to
1378  * avoid leaking orphaned sub-task frames (no cross-coroutine cancellation is
1379  * provided). If every sub-task throws, the first exception observed is
1380  * rethrown from the awaiting @c co_await; an invalid task counts as one
1381  * throwing @c std::logic_error.
1382  *
1383  * @param loop Loop on which sub-tasks are spawned and the caller resumes.
1384  * @param tasks Sub-tasks to race; ownership is transferred into the call.
1385  * @return @c Task resolving to the winning sub-task's index.
1386  * @throws std::invalid_argument if @p tasks is empty; observed at the awaiting
1387  * @c co_await site (since @c when_any is itself a coroutine).
1388  */
1389 VLINK_EXPORT Task<size_t> when_any(MessageLoop& loop, std::vector<Task<void>> tasks);
1390 
1391 /**
1392  * @brief Runs @p tasks sequentially, awaiting each one before starting the next.
1393  *
1394  * @details
1395  * Convenience for composing a linear pipeline of @c Task<void>. Each task is
1396  * spawned on @p loop via the same runner+guard machinery used by @c when_all
1397  * and joined through @c await_future, so both the success path and any
1398  * exception thrown by a sub-task resume the caller on @p loop's thread. If a
1399  * task throws, the exception is rethrown from the awaiting @c co_await with
1400  * its original type preserved and the remaining tasks are skipped. Invalid
1401  * (moved-from or default-constructed) tasks are skipped.
1402  *
1403  * @param loop Loop on which sub-tasks are spawned and the caller resumes.
1404  * @param tasks Sub-tasks to run in order; ownership is transferred into the call.
1405  * @return @c Task<void> that completes once every sub-task has finished or one threw.
1406  */
1407 VLINK_EXPORT Task<void> sequence(MessageLoop& loop, std::vector<Task<void>> tasks);
1408 
1409 ////////////////////////////////////////////////////////////////
1410 /// Details
1411 ////////////////////////////////////////////////////////////////
1412 
1413 namespace detail {
1414 
1415 // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
1416 inline bool FinalAwaiter::await_ready() const noexcept { return false; }
1417 
1418 template <typename PromiseT>
1419 inline std::coroutine_handle<> FinalAwaiter::await_suspend(std::coroutine_handle<PromiseT> handle) noexcept {
1420  auto next = handle.promise().continuation;
1421  return next ? next : std::noop_coroutine();
1422 }
1423 
1424 // NOLINTNEXTLINE(readability-convert-member-functions-to-static)
1425 inline void FinalAwaiter::await_resume() const noexcept {} // LCOV_EXCL_LINE GCOVR_EXCL_LINE
1426 
1427 template <typename TypeT>
1428 inline std::suspend_always TaskPromiseBase<TypeT>::initial_suspend() noexcept {
1429  return {};
1430 }
1431 
1432 template <typename TypeT>
1433 inline FinalAwaiter TaskPromiseBase<TypeT>::final_suspend() noexcept {
1434  return {};
1435 }
1436 
1437 template <typename TypeT>
1438 inline void TaskPromiseBase<TypeT>::unhandled_exception() noexcept {
1439  exception = std::current_exception();
1440 }
1441 
1442 template <typename TypeT>
1443 inline void* TaskPromise<TypeT>::operator new(size_t size) {
1444  return detail::allocate_frame(size);
1445 }
1446 
1447 template <typename TypeT>
1448 inline void TaskPromise<TypeT>::operator delete(void* ptr, size_t size) noexcept {
1449  detail::deallocate_frame(ptr, size);
1450 }
1451 
1452 template <typename TypeT>
1453 inline Task<TypeT> TaskPromise<TypeT>::get_return_object() noexcept {
1454  return Task<TypeT>{std::coroutine_handle<TaskPromise<TypeT>>::from_promise(*this)};
1455 }
1456 
1457 template <typename TypeT>
1458 template <typename UpT>
1459 inline void TaskPromise<TypeT>::return_value(UpT&& v) noexcept(std::is_nothrow_constructible_v<TypeT, UpT&&>) {
1460  result.emplace(std::forward<UpT>(v));
1461 }
1462 
1463 inline void* TaskPromise<void>::operator new(size_t size) { return detail::allocate_frame(size); }
1464 
1465 inline void TaskPromise<void>::operator delete(void* ptr, size_t size) noexcept { detail::deallocate_frame(ptr, size); }
1466 
1467 inline Task<void> TaskPromise<void>::get_return_object() noexcept {
1468  return Task<void>{std::coroutine_handle<TaskPromise<void>>::from_promise(*this)};
1469 }
1470 
1471 inline void TaskPromise<void>::return_void() noexcept {}
1472 
1473 template <typename TypeT, typename CallbackT>
1474 inline DetachedTask co_spawn_value_impl(Task<TypeT> task, CallbackT on_complete) {
1475  on_complete(co_await std::move(task));
1476 }
1477 
1478 template <typename CallbackT>
1479 inline DetachedTask co_spawn_void_with_cb_impl(Task<void> task, CallbackT on_complete) {
1480  co_await std::move(task);
1481  on_complete();
1482 }
1483 
1484 } // namespace detail
1485 
1486 template <typename TypeT>
1487 inline Task<TypeT>::Task(Handle handle) noexcept : handle_(handle) {}
1488 
1489 template <typename TypeT>
1490 inline Task<TypeT>::Task(Task&& other) noexcept : handle_(std::exchange(other.handle_, {})) {}
1491 
1492 template <typename TypeT>
1493 inline Task<TypeT>& Task<TypeT>::operator=(Task&& other) noexcept {
1494  if VLIKELY (this != &other) {
1495  if (handle_) {
1496  handle_.destroy(); // LCOV_EXCL_LINE GCOVR_EXCL_LINE
1497  }
1498  handle_ = std::exchange(other.handle_, {});
1499  }
1500 
1501  return *this;
1502 }
1503 
1504 template <typename TypeT>
1505 inline Task<TypeT>::~Task() {
1506  if (handle_) {
1507  handle_.destroy();
1508  }
1509 }
1510 
1511 template <typename TypeT>
1512 inline bool Task<TypeT>::valid() const noexcept {
1513  return handle_ != nullptr;
1514 }
1515 
1516 template <typename TypeT>
1517 inline bool Task<TypeT>::done() const noexcept {
1518  return handle_ && handle_.done();
1519 }
1520 
1521 template <typename TypeT>
1522 inline bool Task<TypeT>::await_ready() const noexcept {
1523  if VUNLIKELY (!handle_) {
1524  return true;
1525  }
1526 
1527  return handle_.done();
1528 }
1529 
1530 template <typename TypeT>
1531 inline std::coroutine_handle<> Task<TypeT>::await_suspend(std::coroutine_handle<> awaiter) noexcept {
1532  handle_.promise().continuation = awaiter;
1533  return handle_;
1534 }
1535 
1536 template <typename TypeT>
1537 inline TypeT Task<TypeT>::await_resume() {
1538  if VUNLIKELY (!handle_) {
1539  throw std::logic_error("vlink::Coroutine::Task::await_resume on invalid Task (moved-from or default-constructed)");
1540  }
1541 
1542  if VUNLIKELY (handle_.promise().exception) {
1543  std::rethrow_exception(handle_.promise().exception);
1544  }
1545 
1546  if constexpr (!std::is_void_v<TypeT>) {
1547  return std::move(*handle_.promise().result);
1548  }
1549 }
1550 
1551 template <typename TypeT>
1552 inline typename Task<TypeT>::Handle Task<TypeT>::release() noexcept {
1553  return std::exchange(handle_, {});
1554 }
1555 
1556 template <typename TypeT>
1557 inline typename Task<TypeT>::Handle Task<TypeT>::native_handle() const noexcept {
1558  return handle_;
1559 }
1560 
1561 template <typename TypeT>
1562 struct FutureAwaiter<TypeT>::State final {
1563  explicit State(std::future<TypeT> future) noexcept : fut(std::move(future)) {}
1564 
1565  void set_handle(std::coroutine_handle<> h) {
1566  std::lock_guard lock(mtx);
1567 
1568  if (!abandoned.load(std::memory_order_acquire)) {
1569  handle = h;
1570  }
1571  }
1572 
1573  std::coroutine_handle<> take_handle() {
1574  std::lock_guard lock(mtx);
1575  return std::exchange(handle, {});
1576  }
1577 
1578  void clear_handle() {
1579  std::lock_guard lock(mtx);
1580  handle = {};
1581  }
1582 
1583  void resume_ready() {
1584  auto h = take_handle();
1585 
1586  if (h) {
1587  h.resume();
1588  }
1589  }
1590 
1591  void cancel_and_resume() {
1592  target_closed.store(true, std::memory_order_release);
1593  auto h = take_handle();
1594 
1595  if (h) {
1596  h.resume();
1597  }
1598  }
1599 
1600  std::future<TypeT> fut;
1601  std::mutex mtx;
1602  std::coroutine_handle<> handle;
1603  std::atomic_bool abandoned{false};
1604  std::atomic_bool target_closed{false};
1605 };
1606 
1607 template <typename TypeT>
1608 inline FutureAwaiter<TypeT>::FutureAwaiter(MessageLoop* loop, std::future<TypeT> fut) noexcept
1609  : loop_(loop), state_(MemoryResource::make_shared<State>(std::move(fut))) {}
1610 
1611 template <typename TypeT>
1612 inline FutureAwaiter<TypeT>::~FutureAwaiter() {
1613  if (state_) {
1614  state_->abandoned.store(true, std::memory_order_release);
1615  state_->clear_handle();
1616  }
1617 }
1618 
1619 template <typename TypeT>
1620 inline bool FutureAwaiter<TypeT>::await_ready() const noexcept {
1621  return !state_->fut.valid() || state_->fut.wait_for(std::chrono::nanoseconds::zero()) == std::future_status::ready;
1622 }
1623 
1624 template <typename TypeT>
1625 inline void FutureAwaiter<TypeT>::await_suspend(std::coroutine_handle<> handle) {
1626  auto* loop_ptr = loop_;
1627  auto loop_alive = loop_ptr->get_alive_state();
1628  auto state = state_;
1629  state->set_handle(handle);
1630 
1631  const bool deferred = state->fut.wait_for(std::chrono::nanoseconds::zero()) == std::future_status::deferred;
1632 
1633  auto poll = MoveFunction<bool()>([loop_ptr, loop_alive, state = std::move(state),
1634  retry_count = 0U]() mutable -> bool { // LCOV_EXCL_BR_LINE GCOVR_EXCL_BR_LINE
1635  if VUNLIKELY (state->abandoned.load(std::memory_order_acquire)) {
1636  return true; // LCOV_EXCL_LINE GCOVR_EXCL_LINE
1637  }
1638 
1639  if (state->fut.valid() && state->fut.wait_for(std::chrono::nanoseconds::zero()) != std::future_status::ready) {
1640  return false;
1641  }
1642 
1643  const auto result = detail::post_callback_if_alive(
1644  loop_ptr, loop_alive, MoveFunction<void()>([state]() { state->resume_ready(); }),
1645  MoveFunction<void()>([state]() {
1646  detail::register_future_wait(MoveFunction<bool()>([state]() { // LCOV_EXCL_BR_LINE GCOVR_EXCL_BR_LINE
1647  if (!state->abandoned.load(std::memory_order_acquire)) { // LCOV_EXCL_BR_LINE GCOVR_EXCL_BR_LINE
1648  state->cancel_and_resume();
1649  }
1650 
1651  return true;
1652  }));
1653  }));
1654 
1655  if (result == detail::ResumePostResult::kPosted) { // LCOV_EXCL_BR_LINE GCOVR_EXCL_BR_LINE
1656  return true;
1657  }
1658 
1659  if (result == detail::ResumePostResult::kRetry) { // LCOV_EXCL_BR_LINE GCOVR_EXCL_BR_LINE
1660  if (++retry_count >= detail::kMaxResumePostRetry) { // LCOV_EXCL_BR_LINE GCOVR_EXCL_BR_LINE
1661  detail::register_future_wait(MoveFunction<bool()>([state]() { // LCOV_EXCL_BR_LINE GCOVR_EXCL_BR_LINE
1662  if (!state->abandoned.load(std::memory_order_acquire)) { // LCOV_EXCL_BR_LINE GCOVR_EXCL_BR_LINE
1663  state->cancel_and_resume(); // LCOV_EXCL_LINE GCOVR_EXCL_LINE
1664  }
1665  return true; // LCOV_EXCL_LINE GCOVR_EXCL_LINE
1666  }));
1667  return true; // LCOV_EXCL_LINE GCOVR_EXCL_LINE
1668  }
1669 
1670  return false;
1671  }
1672 
1673  return true;
1674  });
1675 
1676  if (deferred) {
1677  if VUNLIKELY (!detail::run_deferred_future([state = state_, poll = std::move(poll)]() mutable {
1678  state->fut.wait();
1679  detail::register_future_wait(std::move(poll));
1680  })) {
1681  throw std::runtime_error("Coroutine::await_future: deferred task post failed");
1682  }
1683  } else {
1684  detail::register_future_wait(std::move(poll));
1685  }
1686 }
1687 
1688 template <typename TypeT>
1689 inline TypeT FutureAwaiter<TypeT>::await_resume() {
1690  state_->abandoned.store(true, std::memory_order_release);
1691  state_->clear_handle();
1692 
1693  if VUNLIKELY (state_->target_closed.load(std::memory_order_acquire)) {
1694  throw Exception::OperationCancelled{};
1695  }
1696 
1697  if VUNLIKELY (!state_->fut.valid()) {
1698  throw Exception::InvalidArgument{"await_future: the future has no shared state"};
1699  }
1700 
1701  if constexpr (std::is_void_v<TypeT>) {
1702  state_->fut.get();
1703  } else {
1704  return state_->fut.get();
1705  }
1706 }
1707 
1708 template <typename TypeT>
1709 inline FutureAwaiter<TypeT> await_future(MessageLoop& loop, std::future<TypeT> fut) noexcept {
1710  return FutureAwaiter<TypeT>{&loop, std::move(fut)};
1711 }
1712 
1713 template <typename TypeT, typename CallbackT, typename>
1714 inline void co_spawn(MessageLoop& loop, Task<TypeT>&& task, CallbackT&& on_complete) {
1715  co_spawn_with_priority<TypeT, CallbackT>(loop, std::move(task), std::forward<CallbackT>(on_complete), 0);
1716 }
1717 
1718 template <typename TypeT, typename CallbackT, typename>
1719 inline void co_spawn_with_priority(MessageLoop& loop, Task<TypeT>&& task, CallbackT&& on_complete, uint16_t priority) {
1720  if constexpr (std::is_void_v<TypeT>) {
1721  auto detached = detail::co_spawn_void_with_cb_impl<std::decay_t<CallbackT>>(std::move(task),
1722  std::forward<CallbackT>(on_complete));
1723  auto handle = detached.handle;
1724  detached.handle = {};
1725  detail::co_spawn_detached_handle(loop, handle, priority);
1726  } else {
1727  auto detached = detail::co_spawn_value_impl<TypeT, std::decay_t<CallbackT>>(std::move(task),
1728  std::forward<CallbackT>(on_complete));
1729  auto handle = detached.handle;
1730  detached.handle = {};
1731  detail::co_spawn_detached_handle(loop, handle, priority);
1732  }
1733 }
1734 
1735 template <typename CallbackT>
1736 inline Task<void> exec(MessageLoop& loop, Schedule::Config config, CallbackT callback) {
1737  std::future<void> fut;
1738 
1739  {
1740  auto promise_ptr = MemoryResource::make_shared<std::promise<void>>();
1741  fut = promise_ptr->get_future();
1742 
1743  auto status = loop.exec_task(config, [cb = std::move(callback), promise_ptr]() mutable {
1744  try {
1745  cb();
1746  promise_ptr->set_value();
1747  } catch (...) {
1748  promise_ptr->set_exception(std::current_exception());
1749  }
1750  });
1751 
1752  if (config.schedule_timeout_ms > 0) {
1753  status.on_schedule_timeout([promise_ptr]() {
1754  promise_ptr->set_exception(std::make_exception_ptr(std::runtime_error("Coroutine::exec: schedule timeout")));
1755  });
1756  }
1757 
1758  if VUNLIKELY (!status.dispatch()) {
1759  promise_ptr->set_exception(std::make_exception_ptr(std::runtime_error("Coroutine::exec: exec_task post failed")));
1760  }
1761  }
1762 
1763  co_await await_future(loop, std::move(fut));
1764 
1765  co_return;
1766 }
1767 
1768 namespace detail {
1769 
1770 template <typename TypeT>
1771 struct WhenAllState final {
1772  std::vector<TypeT> results;
1773  std::atomic<size_t> remaining{0};
1774  std::mutex exc_mtx;
1775  std::exception_ptr first_exc;
1776  std::promise<void> promise;
1777 };
1778 
1779 template <typename TypeT>
1780 struct WhenAllGuard final {
1781  std::shared_ptr<WhenAllState<TypeT>> state;
1782  bool completed_normally{false};
1783 
1784  explicit WhenAllGuard(std::shared_ptr<WhenAllState<TypeT>> s) noexcept : state(std::move(s)) {}
1785 
1786  WhenAllGuard(WhenAllGuard&& other) noexcept
1787  : state(std::move(other.state)), completed_normally(other.completed_normally) {}
1788 
1789  WhenAllGuard(const WhenAllGuard&) = delete;
1790 
1791  WhenAllGuard& operator=(const WhenAllGuard&) = delete;
1792 
1793  WhenAllGuard& operator=(WhenAllGuard&&) = delete;
1794 
1795  ~WhenAllGuard() {
1796  if (!state) {
1797  return;
1798  }
1799 
1800  if (!completed_normally) {
1801  // LCOV_EXCL_START GCOVR_EXCL_START
1802  std::lock_guard lock(state->exc_mtx);
1803 
1804  if (!state->first_exc) {
1805  state->first_exc = std::make_exception_ptr(
1806  std::runtime_error("vlink::Coroutine::when_all: sub-task aborted before completion"));
1807  }
1808  }
1809  // LCOV_EXCL_STOP GCOVR_EXCL_STOP
1810 
1811  if (state->remaining.fetch_sub(1, std::memory_order_acq_rel) == 1) {
1812  if (state->first_exc) {
1813  state->promise.set_exception(state->first_exc);
1814  } else {
1815  state->promise.set_value();
1816  }
1817  }
1818  }
1819 };
1820 
1821 template <typename TypeT>
1822 inline Task<void> when_all_runner(Task<TypeT> task, size_t i, WhenAllGuard<TypeT> guard) {
1823  try {
1824  auto value = co_await std::move(task);
1825  if constexpr (std::is_same_v<TypeT, bool>) {
1826  std::lock_guard lock(guard.state->exc_mtx);
1827  guard.state->results[i] = value;
1828  } else {
1829  guard.state->results[i] = std::move(value);
1830  }
1831  } catch (...) {
1832  std::lock_guard lock(guard.state->exc_mtx);
1833 
1834  if (!guard.state->first_exc) {
1835  guard.state->first_exc = std::current_exception();
1836  }
1837  }
1838 
1839  guard.completed_normally = true;
1840 }
1841 
1842 template <typename TypeT>
1843 struct WhenAnyState final {
1844  std::atomic_bool fired{false};
1845  std::atomic<size_t> remaining{0};
1846  std::mutex exc_mtx;
1847  std::exception_ptr first_exc;
1848  std::optional<std::pair<size_t, TypeT>> winner;
1849  std::promise<std::pair<size_t, TypeT>> promise;
1850 };
1851 
1852 template <typename TypeT>
1853 struct WhenAnyGuard final {
1854  std::shared_ptr<WhenAnyState<TypeT>> state;
1855  bool completed_normally{false};
1856 
1857  explicit WhenAnyGuard(std::shared_ptr<WhenAnyState<TypeT>> s) noexcept : state(std::move(s)) {}
1858 
1859  WhenAnyGuard(WhenAnyGuard&& other) noexcept
1860  : state(std::move(other.state)), completed_normally(other.completed_normally) {}
1861 
1862  WhenAnyGuard(const WhenAnyGuard&) = delete;
1863 
1864  WhenAnyGuard& operator=(const WhenAnyGuard&) = delete;
1865 
1866  WhenAnyGuard& operator=(WhenAnyGuard&&) = delete;
1867 
1868  ~WhenAnyGuard() {
1869  if (!state) {
1870  return;
1871  }
1872 
1873  if (!completed_normally) {
1874  // LCOV_EXCL_START GCOVR_EXCL_START
1875  std::lock_guard lock(state->exc_mtx);
1876 
1877  if (!state->first_exc) {
1878  state->first_exc = std::make_exception_ptr(
1879  std::runtime_error("vlink::Coroutine::when_any: sub-task aborted before completion"));
1880  }
1881  }
1882  // LCOV_EXCL_STOP GCOVR_EXCL_STOP
1883 
1884  if (state->remaining.fetch_sub(1, std::memory_order_acq_rel) == 1) {
1885  if (state->winner) {
1886  state->promise.set_value(std::move(*state->winner));
1887  } else {
1888  state->promise.set_exception(state->first_exc);
1889  }
1890  }
1891  }
1892 };
1893 
1894 template <typename TypeT>
1895 inline Task<void> when_any_runner(Task<TypeT> task, size_t i, WhenAnyGuard<TypeT> guard) {
1896  try {
1897  auto value = co_await std::move(task);
1898  bool expected = false;
1899 
1900  if (guard.state->fired.compare_exchange_strong(expected, true, std::memory_order_acq_rel,
1901  std::memory_order_relaxed)) {
1902  guard.state->winner.emplace(i, std::move(value));
1903  }
1904  } catch (...) {
1905  std::lock_guard lock(guard.state->exc_mtx);
1906 
1907  if (!guard.state->first_exc) {
1908  guard.state->first_exc = std::current_exception();
1909  }
1910  }
1911 
1912  guard.completed_normally = true;
1913 }
1914 
1915 } // namespace detail
1916 
1917 template <typename TypeT>
1918 inline Task<std::vector<TypeT>> when_all(MessageLoop& loop, std::vector<Task<TypeT>> tasks) {
1919  static_assert(std::is_default_constructible_v<TypeT>,
1920  "Co::when_all<T>: T must be default-constructible (results vector pre-sized).");
1921 
1922  if VUNLIKELY (tasks.empty()) {
1923  co_return std::vector<TypeT>{};
1924  }
1925 
1926  const size_t count = tasks.size();
1927  auto state = MemoryResource::make_shared<detail::WhenAllState<TypeT>>();
1928  state->results.resize(count);
1929  state->remaining.store(count, std::memory_order_relaxed);
1930  auto fut = state->promise.get_future();
1931 
1932  for (size_t i = 0; i < count; ++i) {
1933  co_spawn(loop, detail::when_all_runner<TypeT>(std::move(tasks[i]), i, detail::WhenAllGuard<TypeT>{state}));
1934  }
1935 
1936  co_await await_future(loop, std::move(fut));
1937 
1938  co_return std::move(state->results);
1939 }
1940 
1941 template <typename TypeT>
1942 inline Task<std::pair<size_t, TypeT>> when_any(MessageLoop& loop, std::vector<Task<TypeT>> tasks) {
1943  if VUNLIKELY (tasks.empty()) {
1944  throw std::invalid_argument("vlink::Coroutine::when_any: tasks must not be empty");
1945  }
1946 
1947  auto state = MemoryResource::make_shared<detail::WhenAnyState<TypeT>>();
1948  state->remaining.store(tasks.size(), std::memory_order_relaxed);
1949  auto fut = state->promise.get_future();
1950 
1951  for (size_t i = 0; i < tasks.size(); ++i) {
1952  co_spawn(loop, detail::when_any_runner<TypeT>(std::move(tasks[i]), i, detail::WhenAnyGuard<TypeT>{state}));
1953  }
1954 
1955  co_return co_await await_future(loop, std::move(fut));
1956 }
1957 
1958 } // namespace Coroutine
1959 
1960 /**
1961  * @namespace vlink::Co
1962  * @brief Short alias for @c vlink::Coroutine.
1963  *
1964  * @details
1965  * Lets user code write @c vlink::Co::Task / @c vlink::Co::yield(loop) etc.
1966  * @c vlink::Co and @c vlink::Coroutine refer to the same namespace.
1967  */
1968 namespace Co = Coroutine; // NOLINT(readability-identifier-naming)
1969 
1970 } // namespace vlink
1971 
1972 #endif // VLINK_ENABLE_COROUTINE
Thin final wrappers around the standard exception hierarchy used by VLink.
Pool-backed type-erased callables: copyable vlink::Function and move-only vlink::MoveFunction.
Directed acyclic task graph with condition branching, cycle guard and DOT export.
Cross-platform macros for visibility, branch hints, copy prevention, singletons and string helpers.
#define VUNLIKELY(...)
Short alias for VLINK_UNLIKELY.
Definition: macros.h:292
#define VLINK_EXPORT
Definition: macros.h:81
#define VLIKELY(...)
Short alias for VLINK_LIKELY.
Definition: macros.h:284
#define VLINK_DISALLOW_COPY_AND_ASSIGN(classname)
Deletes the copy constructor and copy-assignment operator of classname.
Definition: macros.h:174
PMR adapter that lets standard pmr-aware containers allocate through vlink::MemoryPool.
Single-threaded task dispatcher with three queue backends, timers and scheduling envelopes.
Fluent task-scheduling wrapper used by MessageLoop::exec_task() and family.