69 lines
2.8 KiB
Markdown
69 lines
2.8 KiB
Markdown
# acrux::coroutines
|
|
|
|
A Unity-style coroutine system for C++20, built on `co_await`/`co_yield`. Header-only.
|
|
|
|
```cpp
|
|
#include <acrux/coroutines/Coroutine.h>
|
|
#include <acrux/coroutines/CoroutineRunner.h>
|
|
#include <acrux/coroutines/standard/WaitConditions.h>
|
|
|
|
using namespace acrux::coroutines;
|
|
using namespace acrux::coroutines::standard;
|
|
|
|
Coroutine fadeOut(float& alpha, float delta)
|
|
{
|
|
while (alpha > 0)
|
|
{
|
|
alpha -= delta;
|
|
co_yield waitForSeconds(0.1f);
|
|
}
|
|
}
|
|
|
|
int main()
|
|
{
|
|
CoroutineRunner runner;
|
|
float alpha = 1.0f;
|
|
|
|
CoroutineHandle h = startCoroutine(fadeOut(alpha, 0.1f));
|
|
|
|
while (h.isRunning())
|
|
{
|
|
runner.update(); // call once per frame
|
|
}
|
|
}
|
|
```
|
|
|
|
## Layout
|
|
|
|
```
|
|
include/acrux/coroutines/
|
|
Coroutine.h the Coroutine return type + its promise_type
|
|
CoroutineHandle.h a cheap, hashable value identifying a coroutine
|
|
CoroutineRunner.h the scheduler
|
|
Predicate.h small-buffer-optimized type-erased bool() callable
|
|
standard/
|
|
WaitConditions.h waitForSeconds / waitUntil / waitWhile / waitFor --
|
|
built entirely on the public core API, and not
|
|
depended on by anything above
|
|
test/coroutines/main.cpp a runnable example, also the module's test suite
|
|
docs/coroutines/ one file per type, plus architecture.md and example.md
|
|
```
|
|
|
|
## Three features worth knowing about up front
|
|
|
|
**The scheduler doesn't know about `waitForSeconds`/`waitUntil`/etc.** `Coroutine` accepts `co_yield` of anything invocable as `bool()`. `standard/WaitConditions.h` is just a set of functions returning small callables that satisfy that contract. Writing your own wait condition follows the exact same pattern, without touching the core headers. See `docs/coroutines/architecture.md`.
|
|
|
|
**`CoroutineRunner` can be derived from** to attach extra data to each coroutine it starts -- for example, tagging a coroutine with the game entity it belongs to. `CoroutineHandle` is hashable for this reason, and two protected virtual hooks (`onCoroutineStarted`/`onCoroutineFinished`) keep a subclass's own bookkeeping in sync automatically. See `docs/coroutines/example.md` for a complete example.
|
|
|
|
**A coroutine's children inherit its extra data automatically.** `onCoroutineStarted(handle, parent)` is told which coroutine was resuming when `handle` was started -- whether via `co_yield childTask()` or a direct `startCoroutine()` call made from inside a coroutine's body -- so a subclass can propagate its own per-coroutine data from parent to child with a couple of lines, with no special handling required at the call site that starts the child.
|
|
|
|
## Building
|
|
|
|
```sh
|
|
cmake -S . -B build
|
|
cmake --build build
|
|
ctest --test-dir build
|
|
```
|
|
|
|
Or without CMake: this module has no `.cpp` files to compile, so just add `include/` to your include path.
|