Structured concurrency

Mircea Baja - 7 June 2025

# Structured concurrency

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250607-0-box" width="100%" viewBox="0 0 430 170">
  <style>
    #svg20250607-0-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250607-0-t1 {
      font-family: sans-serif;
      font-size: 16px;
      text-anchor: middle;
      dominant-baseline: middle;
    }
    .svg20250607-0-l1 {
      stroke: #2d93ad;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-0-arrow {
      stroke: #2d93ad;
      stroke-width: 1;
      fill: #2d93ad;
    }
    .svg20250607-0-l2 {
      stroke: #8ea604;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-0-arrow2 {
      stroke: #8ea604;
      stroke-width: 1;
      fill: #8ea604;
    }
    .svg20250607-0-l3 {
      stroke: #9665ac;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-0-arrow3 {
      stroke: #9665ac;
      stroke-width: 1;
      fill: #9665ac;
    }
    .svg20250607-0-l4 {
      stroke: #ee6055;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-0-arrow4 {
      stroke: #ee6055;
      stroke-width: 1;
      fill: #ee6055;
    }
    .svg20250607-0-box_white {
      stroke: #000000;
      stroke-width: 2;
      fill: #ffffff;
    }
  </style>
  <defs>
    <marker id="svg20250607-0-arrow" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-0-arrow"/>
    </marker>
    <marker id="svg20250607-0-arrow2" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-0-arrow2"/>
    </marker>
    <marker id="svg20250607-0-arrow3" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-0-arrow3"/>
    </marker>
    <marker id="svg20250607-0-arrow4" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-0-arrow4"/>
    </marker>
  </defs>
  <path class="svg20250607-0-l1" d="M 48 30 v 123" marker-end="url(#svg20250607-0-arrow)"/>
  <path class="svg20250607-0-l4" d="M 50 30 c 0 60 10 0 75 10" marker-end="url(#svg20250607-0-arrow4)"/>
  <text class="svg20250607-0-t1" x="49" y="15">detached</text>
  <path class="svg20250607-0-l1" d="M 270 30 c 0 20 -10 20 -50 20 s -50 0 -50 20" marker-end="url(#svg20250607-0-arrow)"/>
  <path class="svg20250607-0-l2" d="M 270 30 v 40" marker-end="url(#svg20250607-0-arrow2)"/>
  <path class="svg20250607-0-l3" d="M 270 30 c 0 20 10 20 50 20 s 50 0 50 20" marker-end="url(#svg20250607-0-arrow3)"/>
  <path class="svg20250607-0-l1" d="M 170 113 c 0 20 10 20 50 20 s 50 0 50 20"/>
  <path class="svg20250607-0-l3" d="M 370 113 c 0 20 -10 20 -50 20 s -50 0 -50 20"/>
  <path class="svg20250607-0-l2" d="M 270 113 v 40" marker-end="url(#svg20250607-0-arrow2)"/>
  <path class="svg20250607-0-box_white" d="M 140 82 h 60 v 30 l -60 10 z"/>
  <rect x="240" y="82" width="60" height="30" class="svg20250607-0-box_white"/>
  <path class="svg20250607-0-box_white" d="M 340 82 h 60 v 30 l -60 10 z"/>
  <line class="svg20250607-0-l4" x1="145" y1="115" x2="155" y2="105"/>
  <line class="svg20250607-0-l4" x1="145" y1="105" x2="155" y2="115"/>
  <line class="svg20250607-0-l4" x1="345" y1="115" x2="355" y2="105"/>
  <line class="svg20250607-0-l4" x1="345" y1="105" x2="355" y2="115"/>
  <text class="svg20250607-0-t1" x="270" y="15">wait_any</text>
</svg>
</div>

---

# Structured programming

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250607-1-box" width="100%" viewBox="0 0 800 180">
  <style>
    #svg20250607-1-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250607-1-t1 {
      font-family: sans-serif;
      font-size: 16px;
      text-anchor: middle;
      dominant-baseline: middle;
    }
    .svg20250607-1-l1 {
      stroke: #2d93ad;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-1-arrow {
      stroke: #2d93ad;
      stroke-width: 1;
      fill: #2d93ad;
    }
    .svg20250607-1-l2 {
      stroke: #ee6055;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-1-arrow2 {
      stroke: #ee6055;
      stroke-width: 1;
      fill: #ee6055;
    }
    .svg20250607-1-box_white {
      stroke: #000000;
      stroke-width: 2;
      fill: #ffffff;
    }
  </style>
  <defs>
    <marker id="svg20250607-1-arrow" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-1-arrow"/>
    </marker>
    <marker id="svg20250607-1-arrow2" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-1-arrow2"/>
    </marker>
  </defs>
  <path class="svg20250607-1-l1" d="M 60 30 v 120" marker-end="url(#svg20250607-1-arrow)"/>
  <text class="svg20250607-1-t1" x="60" y="15">sequential</text>
  <path class="svg20250607-1-l2" d="M 140 30 c 0 60 10 0 75 10" marker-end="url(#svg20250607-1-arrow2)"/>
  <text class="svg20250607-1-t1" x="140" y="15">goto</text>
  <rect x="240" y="82" width="60" height="30" class="svg20250607-1-box_white"/>
  <rect x="360" y="82" width="60" height="30" class="svg20250607-1-box_white"/>
  <path class="svg20250607-1-l1" d="M 330 30 c 0 20 -10 20 -30 20 s -30 0 -30 20" marker-end="url(#svg20250607-1-arrow)"/>
  <path class="svg20250607-1-l1" d="M 330 30 c 0 20 10 20 30 20 s 30 0 30 20" marker-end="url(#svg20250607-1-arrow)"/>
  <path class="svg20250607-1-l1" d="M 270 113 c 0 20 10 20 30 20 s 30 0 30 20" marker-end="url(#svg20250607-1-arrow)"/>
  <path class="svg20250607-1-l1" d="M 390 113 c 0 20 -10 20 -30 20 s -30 0 -30 20" marker-end="url(#svg20250607-1-arrow)"/>
  <text class="svg20250607-1-t1" x="330" y="15">if</text>
  <rect x="470" y="82" width="60" height="30" class="svg20250607-1-box_white"/>
  <path class="svg20250607-1-l1" d="M 500 30 v 40" marker-end="url(#svg20250607-1-arrow)"/>
  <path class="svg20250607-1-l1" d="M 500 113 c 70 70 70 -110 15 -40" marker-end="url(#svg20250607-1-arrow)"/>
  <path class="svg20250607-1-l1" d="M 500 113 v 40" marker-end="url(#svg20250607-1-arrow)"/>
  <text class="svg20250607-1-t1" x="500" y="15">loop</text>
  <rect x="670" y="82" width="60" height="30" class="svg20250607-1-box_white"/>
  <path class="svg20250607-1-l1" d="M 630 30 v 58 c 20 -70 70 -40 70 -18" marker-end="url(#svg20250607-1-arrow)"/>
  <path class="svg20250607-1-l1" d="M 700 113 c -5 30 -40 30 -70 -18 v 56" marker-end="url(#svg20250607-1-arrow)"/>
  <text class="svg20250607-1-t1" x="630" y="15">function call</text>
</svg>
</div>

[Nathaniel J. Smith: Notes on structured concurrency, or: Go statement
considered
harmful](https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/)

- `goto` corresponds to low level assembly `jump` instructions
- ends in spagetti code: graphs that do not obviously reduce to sequential
  (i.e. linear)
- replaced with constructs that reduce to sequential
- in modern languages even `goto` is tamed (only jumps within the same
  function)
  - but kept for the three cases where it's needed, new case once every 20 years or so
- structured programming is what enables further high level language constructs
  like RAII

---

# Low level concurrency APIs

```cpp
int WSAAPI WSARecv(
  [in]      SOCKET                             s,
  [in, out] LPWSABUF                           lpBuffers,
  [in]      DWORD                              dwBufferCount,
  [out]     LPDWORD                            lpNumberOfBytesRecvd,
  [in, out] LPDWORD                            lpFlags,
  [in]      LPWSAOVERLAPPED                    lpOverlapped,
  [in]      LPWSAOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
);
```

- Can be called with a pointer to the completion routine (a callback)
- Until that routine is called (or cancelled): the socket, buffer, overlapped
  structure (often a derived type holding more data)
  - need to be kept alive
  - they might be accessed during or after the call to `WSARecv`
- Calling the function is just the beginning, how do we tie things at the end?

---

# Unstructured concurrency

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250607-2-box" width="100%" viewBox="0 0 800 120">
  <style>
    #svg20250607-2-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250607-2-t1 {
      font-family: sans-serif;
      font-size: 16px;
      text-anchor: middle;
      dominant-baseline: middle;
    }
    .svg20250607-2-l1 {
      stroke: #2d93ad;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-2-arrow {
      stroke: #2d93ad;
      stroke-width: 1;
      fill: #2d93ad;
    }
    .svg20250607-2-l2 {
      stroke: #ee6055;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-2-arrow2 {
      stroke: #ee6055;
      stroke-width: 1;
      fill: #ee6055;
    }
    .svg20250607-2-box_white {
      stroke: #000000;
      stroke-width: 2;
      fill: #ffffff;
    }
  </style>
  <defs>
    <marker id="svg20250607-2-arrow" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-2-arrow"/>
    </marker>
    <marker id="svg20250607-2-arrow2" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-2-arrow2"/>
    </marker>
  </defs>
  <path class="svg20250607-2-l2" d="M 30 30 c 0 60 10 0 75 10" marker-end="url(#svg20250607-2-arrow2)"/>
  <text class="svg20250607-2-t1" x="30" y="15">goto</text>
  <path class="svg20250607-2-l1" d="M 138 30 v 60" marker-end="url(#svg20250607-2-arrow)"/>
  <path class="svg20250607-2-l2" d="M 140 30 c 0 60 10 0 75 10" marker-end="url(#svg20250607-2-arrow2)"/>
  <text class="svg20250607-2-t1" x="139" y="15">detached</text>
</svg>
</div>

[Nathaniel J. Smith: Notes on structured concurrency, or: Go statement
considered
harmful](https://vorpus.org/blog/notes-on-structured-concurrency-or-go-statement-considered-harmful/)

Low level C APIs expose a detached behaviour, which on one side might be
necessary*, like `jump` statements in assembly, but we want that wrapped in
structured concurrency primitives that are easier to use correctly.

Detach/fire and forget has issues: lifetime, sharing data e.g. by value, error
propagation.

We don't want to continue to stay low level and error prone.

(*) By the end of this presentation it might be worth going back on the
necessity of this kind of interface

---

# Example bad

```cpp
int value = get_value();
std::shared_ptr<Foo> sharedFoo = get_foo();
{
  const auto lambda = [value, sharedFoo]() -> std::future<void>
  {
    co_await something();
    // "sharedFoo" and "value" have already been destroyed
    // the "shared" pointer didn't accomplish anything
  };
  lambda();
} // the lambda closure object has now gone out of scope
```

- [CP.51: Do not use capturing lambdas that are
  coroutines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#cp51-do-not-use-capturing-lambdas-that-are-coroutines),
  similar incorrect recommendations elsewhere: [A capturing lambda can be a
  coroutine, but you have to save your captures while you still
  can](https://devblogs.microsoft.com/oldnewthing/20211103-00/?p=105870)
- the example uses unstructured concurrency: the `lambda()` is assumed to be
  eager and run in detached mode
- the coding guideline, instead of pointing out to the unstructured concurrency
  as a bad thing, makes recommendations about the usage of `shared_ptr`
  (additional allocations), avoiding using lambda captures, gives up on RAII

---

# Example good: wait_any

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250607-3-box" width="100%" viewBox="0 0 800 180">
  <style>
    #svg20250607-3-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250607-3-t1 {
      font-family: sans-serif;
      font-size: 16px;
      text-anchor: middle;
      dominant-baseline: middle;
    }
    .svg20250607-3-l1 {
      stroke: #2d93ad;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-3-arrow {
      stroke: #2d93ad;
      stroke-width: 1;
      fill: #2d93ad;
    }
    .svg20250607-3-l2 {
      stroke: #8ea604;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-3-arrow2 {
      stroke: #8ea604;
      stroke-width: 1;
      fill: #8ea604;
    }
    .svg20250607-3-l3 {
      stroke: #9665ac;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-3-arrow3 {
      stroke: #9665ac;
      stroke-width: 1;
      fill: #9665ac;
    }
    .svg20250607-3-l4 {
      stroke: #ee6055;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-3-box_white {
      stroke: #000000;
      stroke-width: 2;
      fill: #ffffff;
    }
  </style>
  <defs>
    <marker id="svg20250607-3-arrow" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-3-arrow"/>
    </marker>
    <marker id="svg20250607-3-arrow2" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-3-arrow2"/>
    </marker>
    <marker id="svg20250607-3-arrow3" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-3-arrow3"/>
    </marker>
  </defs>
  <path class="svg20250607-3-l1" d="M 140 30 c 0 20 -10 20 -50 20 s -50 0 -50 20" marker-end="url(#svg20250607-3-arrow)"/>
  <path class="svg20250607-3-l2" d="M 140 30 v 40" marker-end="url(#svg20250607-3-arrow2)"/>
  <path class="svg20250607-3-l3" d="M 140 30 c 0 20 10 20 50 20 s 50 0 50 20" marker-end="url(#svg20250607-3-arrow3)"/>
  <path class="svg20250607-3-l1" d="M 40 113 c 0 20 10 20 50 20 s 50 0 50 20"/>
  <path class="svg20250607-3-l3" d="M 240 113 c 0 20 -10 20 -50 20 s -50 0 -50 20"/>
  <path class="svg20250607-3-l2" d="M 140 113 v 40" marker-end="url(#svg20250607-3-arrow2)"/>
  <path class="svg20250607-3-box_white" d="M 10 82 h 60 v 30 l -60 10 z"/>
  <rect x="110" y="82" width="60" height="30" class="svg20250607-3-box_white"/>
  <path class="svg20250607-3-box_white" d="M 210 82 h 60 v 30 l -60 10 z"/>
  <line class="svg20250607-3-l4" x1="15" y1="115" x2="25" y2="105"/>
  <line class="svg20250607-3-l4" x1="15" y1="105" x2="25" y2="115"/>
  <line class="svg20250607-3-l4" x1="215" y1="115" x2="225" y2="105"/>
  <line class="svg20250607-3-l4" x1="215" y1="105" x2="225" y2="115"/>
  <text class="svg20250607-3-t1" x="140" y="15">wait_any</text>
</svg>
</div>

Easy to say "don't use detached", but what to do instead? What are some
examples of structured concurrency primitives? e.g. `wait_any`:
- we started three tasks
- the second completed first
- the other two are cancelled
- continues when all three are completed (cancelled or otherwise)
- returns the value of winner (second task in this case)

---

# Example good: wait_all

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250607-4-box" width="100%" viewBox="0 0 800 180">
  <style>
    #svg20250607-4-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250607-4-t1 {
      font-family: sans-serif;
      font-size: 16px;
      text-anchor: middle;
      dominant-baseline: middle;
    }
    .svg20250607-4-l1 {
      stroke: #2d93ad;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-4-arrow {
      stroke: #2d93ad;
      stroke-width: 1;
      fill: #2d93ad;
    }
    .svg20250607-4-l2 {
      stroke: #8ea604;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-4-arrow2 {
      stroke: #8ea604;
      stroke-width: 1;
      fill: #8ea604;
    }
    .svg20250607-4-l3 {
      stroke: #9665ac;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-4-arrow3 {
      stroke: #9665ac;
      stroke-width: 1;
      fill: #9665ac;
    }
    .svg20250607-4-l4 {
      stroke: #ee6055;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-4-box_white {
      stroke: #000000;
      stroke-width: 2;
      fill: #ffffff;
    }
  </style>
  <defs>
    <marker id="svg20250607-4-arrow" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-4-arrow"/>
    </marker>
    <marker id="svg20250607-4-arrow2" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-4-arrow2"/>
    </marker>
    <marker id="svg20250607-4-arrow3" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-4-arrow3"/>
    </marker>
  </defs>
  <path class="svg20250607-4-l1" d="M 140 30 c 0 20 -10 20 -50 20 s -50 0 -50 20" marker-end="url(#svg20250607-4-arrow)"/>
  <path class="svg20250607-4-l2" d="M 140 30 v 40" marker-end="url(#svg20250607-4-arrow2)"/>
  <path class="svg20250607-4-l3" d="M 140 30 c 0 20 10 20 50 20 s 50 0 50 20" marker-end="url(#svg20250607-4-arrow3)"/>
  <path class="svg20250607-4-l1" d="M 40 113 c 0 20 10 20 50 20 s 50 0 50 20"/>
  <path class="svg20250607-4-l3" d="M 240 113 c 0 20 -10 20 -50 20 s -50 0 -50 20"/>
  <path class="svg20250607-4-l2" d="M 140 113 v 40" marker-end="url(#svg20250607-4-arrow2)"/>
  <rect x="10" y="82" width="60" height="40" class="svg20250607-4-box_white"/>
  <rect x="110" y="82" width="60" height="30" class="svg20250607-4-box_white"/>
  <rect x="210" y="82" width="60" height="35" class="svg20250607-4-box_white"/>
  <text class="svg20250607-4-t1" x="140" y="15">wait_all</text>
</svg>
</div>

- we started three tasks
- the second completed first, nevermind
- continues when all three are completed
- returns the value of each (e.g. as a tuple)

---

# wait_all cancel

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250607-5-box" width="100%" viewBox="0 0 800 180">
  <style>
    #svg20250607-5-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250607-5-t1 {
      font-family: sans-serif;
      font-size: 16px;
      text-anchor: middle;
      dominant-baseline: middle;
    }
    .svg20250607-5-l1 {
      stroke: #2d93ad;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-5-arrow {
      stroke: #2d93ad;
      stroke-width: 1;
      fill: #2d93ad;
    }
    .svg20250607-5-l2 {
      stroke: #8ea604;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-5-arrow2 {
      stroke: #8ea604;
      stroke-width: 1;
      fill: #8ea604;
    }
    .svg20250607-5-l3 {
      stroke: #9665ac;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-5-arrow3 {
      stroke: #9665ac;
      stroke-width: 1;
      fill: #9665ac;
    }
    .svg20250607-5-l4 {
      stroke: #ee6055;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-5-box_white {
      stroke: #000000;
      stroke-width: 2;
      fill: #ffffff;
    }
  </style>
  <defs>
    <marker id="svg20250607-5-arrow" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-5-arrow"/>
    </marker>
    <marker id="svg20250607-5-arrow2" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-5-arrow2"/>
    </marker>
    <marker id="svg20250607-5-arrow3" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-5-arrow3"/>
    </marker>
  </defs>
  <path class="svg20250607-5-l1" d="M 140 30 c 0 20 -10 20 -50 20 s -50 0 -50 20" marker-end="url(#svg20250607-5-arrow)"/>
  <path class="svg20250607-5-l2" d="M 140 30 v 40" marker-end="url(#svg20250607-5-arrow2)"/>
  <path class="svg20250607-5-l3" d="M 140 30 c 0 20 10 20 50 20 s 50 0 50 20" marker-end="url(#svg20250607-5-arrow3)"/>
  <path class="svg20250607-5-l1" d="M 40 113 c 0 20 10 20 50 20 s 50 0 50 20"/>
  <path class="svg20250607-5-l3" d="M 240 113 c 0 20 -10 20 -50 20 s -50 0 -50 20"/>
  <path class="svg20250607-5-l2" d="M 140 113 v 40" marker-end="url(#svg20250607-5-arrow2)"/>
  <path class="svg20250607-5-box_white" d="M 10 82 h 60 v 30 l -60 10 z"/>
  <rect x="110" y="82" width="60" height="30" class="svg20250607-5-box_white"/>
  <path class="svg20250607-5-box_white" d="M 210 82 h 60 v 30 l -60 10 z"/>
  <line class="svg20250607-5-l4" x1="15" y1="115" x2="25" y2="105"/>
  <line class="svg20250607-5-l4" x1="15" y1="105" x2="25" y2="115"/>
  <circle class="svg20250607-5-l4" cx="117" cy="105" r="4"/>
  <line class="svg20250607-5-l4" x1="215" y1="115" x2="225" y2="105"/>
  <line class="svg20250607-5-l4" x1="215" y1="105" x2="225" y2="115"/>
  <text class="svg20250607-5-t1" x="140" y="15">wait_all</text>
</svg>
</div>

- but when task fails then the remaining are cancelled
- there are quite a lot of similarities in this behaviour to `wait_any`

---

# Structured concurrency

---

# The basics should work

- variable declarations
- if/else
- for loops
- function calls
- RAII
- lambdas
- pass argument by reference

- We've seen that the C++ core guidelines give up on this, [CP.53: Parameters
  to coroutines should not be passed by
  reference](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#cp53-parameters-to-coroutines-should-not-be-passed-by-reference)
- We'll see that the sender/receiver framework partially gives up on this and
  has "algorithms" for basic stuff e.g. `just` for variable declaration,
  `repeat` for loops, `then` for function calls and care is required for things
  being passed to such algorithms (reference, value, moved etc. has to be done
  careful and deliberate).

---

# Example good

```cpp
task<void> async_echo(socket s) {
  buffer buff;
  while (true) {
    std::size_t length = co_await async_read_some(s, buff);
    co_await async_write(s, buff, length);
  }
}
```

- we have local variables: `buff`, `length`
- RAII works: `buff` gets destroyed on scope exit
  - but currently it can't be used for joining async work
- we have a `while(true)` loop
- `async_read_some` takes a reference to the buffer variable

---

# Basic: continuation

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250607-6-box" width="100%" viewBox="0 0 800 210">
  <style>
    #svg20250607-6-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250607-6-t1 {
      font-family: sans-serif;
      font-size: 16px;
      text-anchor: middle;
      dominant-baseline: middle;
    }
    .svg20250607-6-l1 {
      stroke: #2d93ad;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-6-arrow {
      stroke: #2d93ad;
      stroke-width: 1;
      fill: #2d93ad;
    }
    .svg20250607-6-box_white {
      stroke: #000000;
      stroke-width: 2;
      fill: #ffffff;
    }
  </style>
  <defs>
    <marker id="svg20250607-6-arrow" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-6-arrow"/>
    </marker>
  </defs>
  <rect x="100" y="82" width="60" height="30" class="svg20250607-6-box_white"/>
  <path class="svg20250607-6-l1" d="M 60 30 v 58 c 20 -70 70 -40 70 -18" marker-end="url(#svg20250607-6-arrow)"/>
  <path class="svg20250607-6-l1" d="M 130 113 c -5 30 -40 30 -70 -18 v 96" marker-end="url(#svg20250607-6-arrow)"/>
  <rect x="30" y="140" width="60" height="30" class="svg20250607-6-box_white"/>
  <text class="svg20250607-6-t1" x="60" y="15">continuation</text>
</svg>
</div>

- do this, THEN do that

---

# Example bad: std::future

```cpp
std::future<int> f = go_async_work(some_arg);
// attach continuation (hypothetical, not in std)
f.then([](int x) {
  // use x
});
```

- a model where async work is started eager has the issue that attaching the
  continuation is potentially racing with the async work, therefore
  synchronization is required between:
  - the async work providing the result into the `std::future`
  - and the `std::future` setting a continuation to be called when a result is
    available
- a better model is to create lazy work which needs to be started later, but
  gives the opportunity to set the continuation before the async work is
  started, thus avoiding races

---

# Example good: lazy

```cpp
task<void> async_echo(socket s) {
  buffer buff;
  while (true) {
    std::size_t length = co_await async_read_some(s, buff);
    co_await async_write(s, buff, length);
  }
}
```

- for example `co_await async_write(...)`
- `async_echo` runs uninterrupted until a `co_await`
- `async_write` is lazy, does not introduce concurrency yet
- `co_await` introduces concurrency
- but `async_echo` only continues when `co_await` completes

- concurrency introduced by `co_await` does not outlive the parent
- in this form it creates a parent-child relationship that makes `co_await`
  behave **logically** like a function call (except that execution can be
  interleaved at that point with other coroutines while this one waits for the
  child to complete

---

# Chain of continuations

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250607-7-box" width="100%" viewBox="0 0 800 150">
  <style>
    #svg20250607-7-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250607-7-t1 {
      font-family: sans-serif;
      font-size: 16px;
      text-anchor: middle;
      dominant-baseline: middle;
    }
    .svg20250607-7-l1 {
      stroke: #2d93ad;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-7-arrow {
      stroke: #2d93ad;
      stroke-width: 1;
      fill: #2d93ad;
    }
    .svg20250607-7-box_white {
      stroke: #000000;
      stroke-width: 2;
      fill: #ffffff;
    }
  </style>
  <defs>
    <marker id="svg20250607-7-arrow" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-7-arrow"/>
    </marker>
  </defs>
  <rect x="100" y="82" width="60" height="30" class="svg20250607-7-box_white"/>
  <path class="svg20250607-7-l1" d="M 60 30 v 58 c 20 -70 70 -40 70 -18" marker-end="url(#svg20250607-7-arrow)"/>
  <path class="svg20250607-7-l1" d="M 130 113 c -5 30 -40 30 -70 -18 v 36" marker-end="url(#svg20250607-7-arrow)"/>
  <rect x="170" y="82" width="60" height="30" class="svg20250607-7-box_white"/>
  <path class="svg20250607-7-l1" d="M 130 88 c 20 -70 70 -40 70 -18" marker-end="url(#svg20250607-7-arrow)"/>
  <path class="svg20250607-7-l1" d="M 200 113 c -5 30 -40 30 -66 -16" marker-end="url(#svg20250607-7-arrow)"/>
  <rect x="240" y="82" width="60" height="30" class="svg20250607-7-box_white"/>
  <path class="svg20250607-7-l1" d="M 200 88 c 20 -70 70 -40 70 -18" marker-end="url(#svg20250607-7-arrow)"/>
  <path class="svg20250607-7-l1" d="M 270 113 c -5 30 -40 30 -66 -16" marker-end="url(#svg20250607-7-arrow)"/>
  <rect x="310" y="82" width="60" height="30" class="svg20250607-7-box_white"/>
  <path class="svg20250607-7-l1" d="M 270 88 c 20 -70 70 -40 70 -18" marker-end="url(#svg20250607-7-arrow)"/>
  <path class="svg20250607-7-l1" d="M 340 113 c -5 30 -40 30 -66 -16" marker-end="url(#svg20250607-7-arrow)"/>
  <text class="svg20250607-7-t1" x="240" y="15">chain</text>
</svg>
</div>

- it is dynamic over time: further links are added to the right or they go away
- it has a root, it starts somewhere
- it has a leaf terminal

- only the leaf has at a certain point in time a pending operation that in
  effect the whole chain is waiting on
- only the leaf needs to register a `stop_callback` to react to cancellation
- if this is a chain of coroutines then it can go to the root and destroy the
  root coroutine, which in turn via RAII will destroy it's child, which in turn
  via RAII ...

---

# Example

```cpp
task<void> async_echo(socket s) {
  buffer buff;
  while (true) {
    std::size_t length = co_await async_read_some(s, buff);
    co_await async_write(s, buff, length);
  }
}
```

- `async_echo` might have a parent
- the parent of `async_echo` (etc.), `async_echo` and e.g. `async_read_some` make a chain
- `async_read_some` and `async_write` are leaves (at different points in time)
  - and illustrate how a chain shortens and lengthens

---

# Chain root

```cpp
co<int> async_foo()
{
  co_return 42;
};

TEST(run_co_return_int)
{
  int result = run(async_foo());

ASSERT_EQ(42, result);
}
```

- `run` blocks the thread until `async_foo` completes and returns whatever
  `async_foo` `co_return`s.
- the chain root needs to have the callback that is called when the entry point
  in the chain eventually completes
  - in the meantime this `run` needs to go though the list of ready tasks and
    timers
- there can be all sort of such `run` functions that differ on what they
  actually do until the entry points completes

---

# Ready queue + timers heap

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250607-8-box" width="100%" viewBox="0 0 800 320">
  <style>
    #svg20250607-8-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250607-8-queue {
      fill: #f4e04d;
    }
    .svg20250607-8-queue2 {
      stroke: #000000;
      stroke-width: 4;
      fill: #f2ed6f;
    }
    .svg20250607-8-l0 {
      stroke: #000000;
      stroke-width: 4;
      fill: none;
    }
    .svg20250607-8-t1 {
      stroke: #000000;
      stroke-width: 4;
      fill: #cee397;
    }
    .svg20250607-8-t2 {
      stroke: #000000;
      stroke-width: 4;
      fill: #cccccc;
    }
    .svg20250607-8-l1 {
      stroke: #000000;
      stroke-width: 2;
      fill: none;
    }
    .svg20250607-8-l2 {
      stroke: #000000;
      stroke-width: 2;
      fill: none;
      stroke-dasharray: 5;
    }
    .svg20250607-8-tx {
      font-family: sans-serif;
      font-size: 16px;
      dominant-baseline: middle;
    }
  </style>
  <defs>
    <marker id="svg20250607-8-arrow" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z"/>
    </marker>
  </defs>
  <rect x="20" y="40" width="260" height="170" class="svg20250607-8-queue"/>
  <rect x="30" y="50" width="80" height="150" class="svg20250607-8-queue2"/>
  <path class="svg20250607-8-l0" d="M 40 180 h 60"/>
  <path class="svg20250607-8-l0" d="M 40 160 h 60"/>
  <path class="svg20250607-8-l0" d="M 40 140 h 60"/>
  <rect x="150" y="120" width="120" height="80" class="svg20250607-8-queue2"/>
  <path class="svg20250607-8-l0" d="M 180 180 h 60"/>
  <path class="svg20250607-8-l0" d="M 160 160 h 60"/>
  <path class="svg20250607-8-l0" d="M 200 140 h 60"/>
  <circle cx="140" cy="270" r="40" class="svg20250607-8-t1"/>
  <circle cx="360" cy="270" r="40" class="svg20250607-8-t2"/>
  <path class="svg20250607-8-l1" d="M 70 200 l 42 32" marker-end="url(#svg20250607-8-arrow)"/>
  <path class="svg20250607-8-l2" d="M 100 270 h -85 v -240 h 35 v 12" marker-end="url(#svg20250607-8-arrow)"/>
  <path class="svg20250607-8-l1" d="M 210 200 l -42 32" marker-end="url(#svg20250607-8-arrow)"/>
  <path class="svg20250607-8-l2" d="M 180 270 h 105 v -170 h -75 v 12" marker-end="url(#svg20250607-8-arrow)"/>
  <path class="svg20250607-8-l2" d="M 400 270 h 15 v -240 h -325 v 12" marker-end="url(#svg20250607-8-arrow)"/>
  <text class="svg20250607-8-tx" x="120" y="60">ready queue</text>
  <text class="svg20250607-8-tx" x="150" y="90">timers heap</text>
</svg>
</div>

- a useful run loop uses a ready queue and timers heap (directly or
  indirectly). Example shows a T1 model directly using them

---

# Run loops, sync_wait

Not all the run loops are the same:

- the simplest one `sync_wait` does not even "run" or "loop" anything
  - it effectively blocks the thread waiting for something else to do the work
  - used in `main` for "demo" examples
  - if used in a thread from a thread pool it can/will case the issue where the
    thread is taken out of the "active" ones in the pool
- some can run their own ready queue and timers heap directly
- others use (blocking) APIs that are required by yet other APIs (e.g. in
  Windows `ReadFileEx` requires a `WaitFor...Ex`)
  - unfortunately different sets of APIs require different kinds of run loops

---

# Detached entry in main

- the whole point of this presentation is: avoid detached, what to do instead

However:
- in an embedded environment it makes sense to setup things in main, and exit
  main while work continues driven e.g. by interrupts, making the entry point
  detached

---

# Chain leaf

```cpp
task<void> async_echo(socket s) {
  buffer buff;
  while (true) {
    std::size_t length = co_await async_read_some(s, buff);
    co_await async_write(s, buff, length);
  }
}
```

- the leaves `async_read_some`, `async_write`
- they have to (eventually) provide an awaiter that implements `await_ready`,
  `await_suspend` and `await_result`
- coroutines require a (nominal) allocation
- leaves are not coroutines, this can avoid allocations (in most cases)
  - as you think about the (temporarily dynamic) tree of a shrinking and
    growing chain: there are a lot of leaves, therefore a lot of allocations
    are avoided
- from the programmer's point of view writing a leaf is a different (and
  relatively difficult) world from using them in a coroutine (simple)

---

# Elementary leaves

```cpp
// sleep for 10 seconds
co_await async_sleep_for(10s);

// give other chains a chance to run
co_await async_yield();

// check if cancelled
co_await async_noop();

// suspend forever (i.e. until cancelled)
co_await async_suspend_forever();
```

---

# wait_any

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250607-9-box" width="100%" viewBox="0 0 800 180">
  <style>
    #svg20250607-9-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250607-9-t1 {
      font-family: sans-serif;
      font-size: 16px;
      text-anchor: middle;
      dominant-baseline: middle;
    }
    .svg20250607-9-l1 {
      stroke: #2d93ad;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-9-arrow {
      stroke: #2d93ad;
      stroke-width: 1;
      fill: #2d93ad;
    }
    .svg20250607-9-l2 {
      stroke: #8ea604;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-9-arrow2 {
      stroke: #8ea604;
      stroke-width: 1;
      fill: #8ea604;
    }
    .svg20250607-9-l3 {
      stroke: #9665ac;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-9-arrow3 {
      stroke: #9665ac;
      stroke-width: 1;
      fill: #9665ac;
    }
    .svg20250607-9-l4 {
      stroke: #ee6055;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-9-box_white {
      stroke: #000000;
      stroke-width: 2;
      fill: #ffffff;
    }
  </style>
  <defs>
    <marker id="svg20250607-9-arrow" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-9-arrow"/>
    </marker>
    <marker id="svg20250607-9-arrow2" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-9-arrow2"/>
    </marker>
    <marker id="svg20250607-9-arrow3" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-9-arrow3"/>
    </marker>
  </defs>
  <path class="svg20250607-9-l1" d="M 140 30 c 0 20 -10 20 -50 20 s -50 0 -50 20" marker-end="url(#svg20250607-9-arrow)"/>
  <path class="svg20250607-9-l2" d="M 140 30 v 40" marker-end="url(#svg20250607-9-arrow2)"/>
  <path class="svg20250607-9-l3" d="M 140 30 c 0 20 10 20 50 20 s 50 0 50 20" marker-end="url(#svg20250607-9-arrow3)"/>
  <path class="svg20250607-9-l1" d="M 40 113 c 0 20 10 20 50 20 s 50 0 50 20"/>
  <path class="svg20250607-9-l3" d="M 240 113 c 0 20 -10 20 -50 20 s -50 0 -50 20"/>
  <path class="svg20250607-9-l2" d="M 140 113 v 40" marker-end="url(#svg20250607-9-arrow2)"/>
  <path class="svg20250607-9-box_white" d="M 10 82 h 60 v 30 l -60 10 z"/>
  <rect x="110" y="82" width="60" height="30" class="svg20250607-9-box_white"/>
  <path class="svg20250607-9-box_white" d="M 210 82 h 60 v 30 l -60 10 z"/>
  <line class="svg20250607-9-l4" x1="15" y1="115" x2="25" y2="105"/>
  <line class="svg20250607-9-l4" x1="15" y1="105" x2="25" y2="115"/>
  <line class="svg20250607-9-l4" x1="215" y1="115" x2="225" y2="105"/>
  <line class="svg20250607-9-l4" x1="215" y1="105" x2="225" y2="115"/>
  <text class="svg20250607-9-t1" x="140" y="15">wait_any</text>
</svg>
</div>

- is a leaf for a chain, but then it creates roots for the children chains
- each of those roots has callbacks
- when the callback for a child chain is called
  - if it's the first one, then cancel the others
- when no error: returns the result of the first chain
  - and info: which one completed?
- also if the chain for which `wait_any` is a leaf is cancelled then the
  remaining children are cancelled

---

# Callback, callback, callback

The terminology is a little bit overloaded:

- a root of a chain has some work to do when it's cancelled (e.g. destroy the
  first coroutine in the chain that will recursively destroy the chain):
  **cancellation callback** for a root of a chain
  - similarly some work to do when it completes successfully: **completion
    callback**
- a good tool to implement cancellation is the triad:
  `stop_source`/`stop_stoken`/**`stop_callback`**
- the `stop_callback` takes a functor of the work to do when cancelled (which
  eventually leads to the cancellation callback at the root of the chain to be
  called
- **our class `callback`** captures a `void*` and a function pointer and can be
  used:
  - as such a functor for `stop_callback`, though our `stop_callback`
    integrates better with it that the `std::[inplace_]stop_callback` does
  - or as a chain root cancellation or completion callback
- **a completion routine** for a C API such as the one for `WSARecv` is called
  a callback

- we'll have a more complete picture when we talk about
  [cancellation](/presentations/2025-07-18-cancellation.html)

---

# wait_any

```cpp
co<size_t> async_some_wait()
{
  auto result = co_await async_wait_any(
    async_suspend_forever(),
    async_sleep_for(std::chrono::seconds(0))
  );
  co_return result.index;
}

TEST(wait_any_inside_co)
{
  auto result = run(async_some_wait());
  ASSERT_EQ(1, result);
}
```

---

# wait_all

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250607-10-box" width="100%" viewBox="0 0 800 180">
  <style>
    #svg20250607-10-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250607-10-t1 {
      font-family: sans-serif;
      font-size: 16px;
      text-anchor: middle;
      dominant-baseline: middle;
    }
    .svg20250607-10-l1 {
      stroke: #2d93ad;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-10-arrow {
      stroke: #2d93ad;
      stroke-width: 1;
      fill: #2d93ad;
    }
    .svg20250607-10-l2 {
      stroke: #8ea604;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-10-arrow2 {
      stroke: #8ea604;
      stroke-width: 1;
      fill: #8ea604;
    }
    .svg20250607-10-l3 {
      stroke: #9665ac;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-10-arrow3 {
      stroke: #9665ac;
      stroke-width: 1;
      fill: #9665ac;
    }
    .svg20250607-10-l4 {
      stroke: #ee6055;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-10-box_white {
      stroke: #000000;
      stroke-width: 2;
      fill: #ffffff;
    }
  </style>
  <defs>
    <marker id="svg20250607-10-arrow" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-10-arrow"/>
    </marker>
    <marker id="svg20250607-10-arrow2" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-10-arrow2"/>
    </marker>
    <marker id="svg20250607-10-arrow3" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-10-arrow3"/>
    </marker>
  </defs>
  <path class="svg20250607-10-l1" d="M 140 30 c 0 20 -10 20 -50 20 s -50 0 -50 20" marker-end="url(#svg20250607-10-arrow)"/>
  <path class="svg20250607-10-l2" d="M 140 30 v 40" marker-end="url(#svg20250607-10-arrow2)"/>
  <path class="svg20250607-10-l3" d="M 140 30 c 0 20 10 20 50 20 s 50 0 50 20" marker-end="url(#svg20250607-10-arrow3)"/>
  <path class="svg20250607-10-l1" d="M 40 113 c 0 20 10 20 50 20 s 50 0 50 20"/>
  <path class="svg20250607-10-l3" d="M 240 113 c 0 20 -10 20 -50 20 s -50 0 -50 20"/>
  <path class="svg20250607-10-l2" d="M 140 113 v 40" marker-end="url(#svg20250607-10-arrow2)"/>
  <rect x="10" y="82" width="60" height="40" class="svg20250607-10-box_white"/>
  <rect x="110" y="82" width="60" height="30" class="svg20250607-10-box_white"/>
  <rect x="210" y="82" width="60" height="35" class="svg20250607-10-box_white"/>
  <text class="svg20250607-10-t1" x="140" y="15">wait_all</text>
</svg>
</div>

- is a leaf for a chain, but then it creates roots for the children chains
- each of those roots has callbacks
- when the callback for a child chain is called
  - if it's the first one to have an error, then cancel the others
- when no error: it returns a tuple of the results of each chain

---

# wait_all

```cpp
TEST(wait_all_tree)
{
  auto result = run(coro_st::async_wait_any(
    async_suspend_forever(),
    async_wait_all(
      std::invoke([]() -> co<int> {
        co_return 42;
      }),
      async_yield()
    )
  ));
  ASSERT_EQ(1, result.index);
  ASSERT_EQ(42, std::get<0>(result.value));
}
```

---

# wait_for

```cpp
co<int> async_some_int()
{
  co_await async_yield();
  co_return 42;
}

TEST(wait_for_int_has_value)
{
  auto result = run(async_wait_for(
    async_some_int(),
    std::chrono::hours(24)
  ));
  ASSERT_TRUE(result.has_value());
  ASSERT_EQ(42, result.value());
}
```

- it's so common do to an operation, but only willing to wait a certain amount
  of time
- could use `wait_any`, but `wait_for` is easier to use for this common
  scenario
- returns a `std::nullopt` if the time was hit and work was cancelled

---

# stop_when

```cpp
std::optional<int> result1 = co_await async_wait_for(
  async_some_int(),
  std::chrono::minutes(2)
));

std::optional<int> result2 = co_await async_stop_when(
  async_some_int(),
  async_sleep_for(std::chrono::minutes(2))
));

std::optional<int> result3 = co_await async_stop_when(
  async_some_int(),
  async_ctrl_c_pressed()
));
```

- is a generalisation of `wait_for`, where the "stopping" async activity is
  provided explicitly

---

# Nursery

- a dynamic version of `wait_[all|any]`
- nursery = "that's where the children live"
- partially relaxes structured concurrency principles to achieve functionality
  that's hard otherwise

---

# Nursery: the server case

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250607-11-box" width="100%" viewBox="0 0 800 230">
  <style>
    #svg20250607-11-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250607-11-t1 {
      font-family: sans-serif;
      font-size: 16px;
      text-anchor: middle;
      dominant-baseline: middle;
    }
    .svg20250607-11-l1 {
      stroke: #2d93ad;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-11-arrow {
      stroke: #2d93ad;
      stroke-width: 1;
      fill: #2d93ad;
    }
    .svg20250607-11-l2 {
      stroke: #8ea604;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-11-arrow2 {
      stroke: #8ea604;
      stroke-width: 1;
      fill: #8ea604;
    }
    .svg20250607-11-l3 {
      stroke: #9665ac;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-11-arrow3 {
      stroke: #9665ac;
      stroke-width: 1;
      fill: #9665ac;
    }
    .svg20250607-11-l4 {
      stroke: #ee6055;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-11-box_white {
      stroke: #000000;
      stroke-width: 2;
      fill: #ffffff;
    }
  </style>
  <defs>
    <marker id="svg20250607-11-arrow" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-11-arrow"/>
    </marker>
    <marker id="svg20250607-11-arrow2" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-11-arrow2"/>
    </marker>
    <marker id="svg20250607-11-arrow3" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-11-arrow3"/>
    </marker>
  </defs>
  <path class="svg20250607-11-l1" d="M 40 30 v 28" marker-end="url(#svg20250607-11-arrow)"/>
  <path class="svg20250607-11-l2" d="M 70 90 h 29" marker-end="url(#svg20250607-11-arrow2)"/>
  <path class="svg20250607-11-l3" d="M 70 130 h 129" marker-end="url(#svg20250607-11-arrow3)"/>
  <path class="svg20250607-11-l2" d="M 140 130 v 20 c 0 20 -10 20 -50 20 s -50 0 -50 20"/>
  <path class="svg20250607-11-l1" d="M 40 160 v 50"/>
  <path class="svg20250607-11-l3" d="M 240 170 c 0 20 -10 20 -100 20 s -100 0 -100 20" marker-end="url(#svg20250607-11-arrow3)"/>
  <rect x="10" y="70" width="60" height="20" class="svg20250607-11-box_white"/>
  <rect x="10" y="90" width="60" height="40" class="svg20250607-11-box_white"/>
  <rect x="10" y="130" width="60" height="30" class="svg20250607-11-box_white"/>
  <rect x="110" y="90" width="60" height="60" class="svg20250607-11-box_white"/>
  <rect x="210" y="130" width="60" height="40" class="svg20250607-11-box_white"/>
  <text class="svg20250607-11-t1" x="40" y="15">server</text>
  <text class="svg20250607-11-t1" x="140" y="70">connection</text>
  <text class="svg20250607-11-t1" x="240" y="110">connection</text>
</svg>
</div>

- main chain loops waiting for connections
- each connection spawns a new chain
- orderly shutdown

---

# Nursery: the server case

```cpp
co<void> async_accept_loop(nursery& n) {
  auto ep = co_await async_tcp_listen(8080);
  while (true) {
    auto socket = co_await async_tcp_accept(ep);
    n.spawn_child(async_echo, std::move(socket));
  }
}

co<void> async_server() {
  nursery n;
  co_await n.async_run(
    async_accept_loop(n));
}
```

- the entry point usually takes it by reference
- has `spawn_child` and `request_stop`
- `spawn_child` has captures arguments similar to `std::bind`
  - e.g. to pass reference use `std::ref`
  - allocated to outlive the scope of the call

---

# Nursery: the proxy detection case

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250607-12-box" width="100%" viewBox="0 0 800 230">
  <style>
    #svg20250607-12-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250607-12-t1 {
      font-family: sans-serif;
      font-size: 16px;
      text-anchor: middle;
      dominant-baseline: middle;
    }
    .svg20250607-12-l1 {
      stroke: #2d93ad;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-12-arrow {
      stroke: #2d93ad;
      stroke-width: 1;
      fill: #2d93ad;
    }
    .svg20250607-12-l2 {
      stroke: #8ea604;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-12-arrow2 {
      stroke: #8ea604;
      stroke-width: 1;
      fill: #8ea604;
    }
    .svg20250607-12-l3 {
      stroke: #9665ac;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-12-arrow3 {
      stroke: #9665ac;
      stroke-width: 1;
      fill: #9665ac;
    }
    .svg20250607-12-l4 {
      stroke: #ee6055;
      stroke-width: 3;
      fill: none;
    }
    .svg20250607-12-box_white {
      stroke: #000000;
      stroke-width: 2;
      fill: #ffffff;
    }
  </style>
  <defs>
    <marker id="svg20250607-12-arrow" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-12-arrow"/>
    </marker>
    <marker id="svg20250607-12-arrow2" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-12-arrow2"/>
    </marker>
    <marker id="svg20250607-12-arrow3" viewBox="0, 0, 10, 10" refX="5" refY="5" markerWidth="6" markerHeight="6" orient="auto-start-reverse">
      <path d="M 0 0 L 10 5 L 0 10 L 2.5 5 Z" class="svg20250607-12-arrow3"/>
    </marker>
  </defs>
  <path class="svg20250607-12-l1" d="M 40 30 v 28" marker-end="url(#svg20250607-12-arrow)"/>
  <path class="svg20250607-12-l2" d="M 70 70 h 29" marker-end="url(#svg20250607-12-arrow2)"/>
  <path class="svg20250607-12-l3" d="M 170 110 h 29" marker-end="url(#svg20250607-12-arrow3)"/>
  <path class="svg20250607-12-l1" d="M 40 130 v 60"/>
  <path class="svg20250607-12-l3" d="M 240 140 c 0 20 -10 20 -100 20 s -100 0 -100 20"/>
  <path class="svg20250607-12-l2" d="M 140 130 v 5 c 0 20 -10 20 -50 20 s -50 0 -50 20 v 15" marker-end="url(#svg20250607-12-arrow2)"/>
  <rect x="10" y="70" width="60" height="60" class="svg20250607-12-box_white"/>
  <rect x="110" y="70" width="60" height="40" class="svg20250607-12-box_white"/>
  <rect x="110" y="110" width="60" height="25" class="svg20250607-12-box_white"/>
  <rect x="210" y="110" width="60" height="30" class="svg20250607-12-box_white"/>
  <circle class="svg20250607-12-l4" cx="117" cy="128" r="4"/>
  <line class="svg20250607-12-l4" x1="215" y1="136" x2="225" y2="126"/>
  <line class="svg20250607-12-l4" x1="215" y1="126" x2="225" y2="136"/>
  <text class="svg20250607-12-t1" x="40" y="15">proxy 0</text>
  <text class="svg20250607-12-t1" x="140" y="50">proxy 1</text>
  <text class="svg20250607-12-t1" x="240" y="90">proxy 2</text>
</svg>
</div>

- try a proxy
- 100ms later try another one
- first one to complete wins

---

# Nursery: the proxy detection case

```cpp
co<void> async_try_proxy(nursery& n,
    const std::vector<proxy>& proxies, size_t i,
    std::optional<size_t>& result) {
  if (i != 0) { co_await async_sleep_for(100ms); }
  if (i + 1 < proxies.size()) {
    n.spawn_child(async_try_proxy, std::ref(n), std::ref(proxies), i + 1, std::ref(result));
  }
  try {
    co_await async_actually_try_proxy(proxy);
    result = i;
    n.request_stop();
  } catch(...) {
  }
}

co<std::optional<size_t>> async_detect_proxy(const std::vector<proxy>& proxies) {
  std::optional<size_t> result;
  nursery n;
  co_await n.async_run(
    async_try_proxy(n, proxies, 0, result));
  co_return result;
}
```

---

# Mildly unstructured (again)

- we'll see in the cancellation presentation that actually the structured
  concurrency primitives imply a two step process: setting the continuation
  before starting the work
- but in the (good) examples I hid that detail and stuck to the structured
  concurrency principles that make it easy to reason about code
- we only relaxed it a bit for the nursery

- but not all the libraries are strict about it
- bad (in my opinion)

---

# Example bad

```cpp
co<void> async_should_not_compile() {
  auto x = async_foo("some string");
  co_await std::move(x);
}
```

- some libraries allow the above to compile, but this creates issues similar to
  the generator
- we've seen that the C++ core guidelines give up on this, [CP.53: Parameters
  to coroutines should not be passed by
  reference](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#cp53-parameters-to-coroutines-should-not-be-passed-by-reference)
  - despite plenty of cases where things should be passed by reference and the
    case where "values" of the like `std::string_view` are still references in
    disguise

- my observation is that programmers when taught about such issue nod, but then
  end up learning the hard way (i.e. via bugs) and end up drawing the wrong
  conclusion (i.e. don't use references for coroutine parameters) instead of
  using/creating libraries that stop bad patterns

---

# Questions?