Stop source, token, callback

Mircea Baja - 3 June 2025

# Stop source, token, callback

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250603-0-box" width="100%" viewBox="0 0 800 300">
  <style>
    #svg20250603-0-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250603-0-stop_border {
      stroke: #000000;
      stroke-width: 4;
      fill: none;
    }
    .svg20250603-0-stop_sign {
      stroke: #ffffff;
      stroke-width: 16;
      fill: #ce2029;
    }
    .svg20250603-0-stop_word {
      stroke: #ffffff;
      stroke-width: 16;
      fill: none;
    }
  </style>
  <path class="svg20250603-0-stop_sign" d="M 113 15 h 138 l 100 100 v 136 l -100 100 h -138 l -100 -100 v -136 z"/>
  <path class="svg20250603-0-stop_border" d="M 110 10 h 144 l 100 100 v 144 l -100 100 h -144 l -100 -100 v -144 z"/>
  <path class="svg20250603-0-stop_word" d="M 100 160q 0 -20 -20 -20 q -20 0 -20 20 q 0 10 20 20q 20 10 20 20 q 0 20 -20 20 q -20 0 -20 -20"/>
  <path class="svg20250603-0-stop_word" d="M 115 140 h 60 h -30 v 88"/>
  <ellipse class="svg20250603-0-stop_word" cx="215" cy="180" rx="30" ry="40"/>
  <path class="svg20250603-0-stop_word" d="M 275 228 v -88 h 20 a 20 20 0 0 1 0 40 h -20"/>
</svg>
</div>

---

# Motivation

- what do we need to implement cancellation?
- std has `std::stop_source`, `std::stop_token` and `std::stop_callback`
- introduced for `std::jthread` in C++20
- how do they work?
- let's explore single threaded variants

---

# Dummy stop source and token

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250603-1-box" width="100%" viewBox="0 0 800 300">
  <style>
    #svg20250603-1-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250603-1-t1 {
      font-family: sans-serif;
      font-size: 16px;
      dominant-baseline: middle;
    }
    .svg20250603-1-l1 {
      stroke: #000000;
      stroke-width: 2;
      fill: none;
    }
    .svg20250603-1-l2 {
      stroke: #000000;
      stroke-dasharray: 5;
      stroke-width: 2;
      fill: none;
    }
    .svg20250603-1-task_white {
      stroke: #000000;
      stroke-width: 4;
      fill: #ffffff;
    }
    .svg20250603-1-task_orange {
      stroke: #000000;
      stroke-width: 4;
      fill: #f5bb00;
    }
    .svg20250603-1-task_red {
      stroke: #000000;
      stroke-width: 4;
      fill: #ee6055;
    }
  </style>
  <defs>
    <marker id="svg20250603-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"/>
    </marker>
  </defs>
  <rect x="30" y="10" width="100" height="250" class="svg20250603-1-task_white"/>
  <path class="svg20250603-1-l1" d="M 80 30 v 215 h -60" marker-end="url(#svg20250603-1-arrow)"/>
  <rect x="180" y="40" width="100" height="30" class="svg20250603-1-task_orange"/>
  <text class="svg20250603-1-t1" x="190" y="55">ref</text>
  <rect x="180" y="150" width="100" height="30" class="svg20250603-1-task_red"/>
  <text class="svg20250603-1-t1" x="190" y="165">stop</text>
  <path class="svg20250603-1-l1" d="M 230 70 v 72" marker-end="url(#svg20250603-1-arrow)"/>
  <path class="svg20250603-1-l2" d="M 80 40 h 92" marker-end="url(#svg20250603-1-arrow)"/>
  <path class="svg20250603-1-l2" d="M 80 140 h 25 v -83 h 67" marker-end="url(#svg20250603-1-arrow)"/>
  <path class="svg20250603-1-l2" d="M 80 240 h 75 v -170 h 17" marker-end="url(#svg20250603-1-arrow)"/>
  <text class="svg20250603-1-t1" x="140" y="25">token.stop_requested()</text>
  <rect x="330" y="10" width="100" height="280" class="svg20250603-1-task_white"/>
  <path class="svg20250603-1-l1" d="M 380 30 v 230" marker-end="url(#svg20250603-1-arrow)"/>
  <path class="svg20250603-1-l2" d="M 380 165 h -92" marker-end="url(#svg20250603-1-arrow)"/>
  <text class="svg20250603-1-t1" x="440" y="160">source.request_stop()</text>
</svg>
</div>

- `stop` has a one way transition from `false` to `true`, `stop_token` holder cannot
  `request_stop()`
- `stop_token` holder can poll using `stop_requested()`

---

# Dummy stop source

```cpp
class stop_source
{
  bool stop_{ false };
public:
  stop_source() noexcept = default;

stop_source(const stop_source&) = delete;
  stop_source& operator=(const stop_source&) = delete;

bool stop_requested() const noexcept {
    return stop_;
  }

bool request_stop() noexcept {
    if (stop_) { return false; }
    stop_ = true; return true;
  }

stop_token get_token() noexcept {
    return stop_token{ this };
  }
}; // dummy stop_source
```

---

# Dummy stop token

```cpp
class stop_token
{
  friend stop_source;

stop_source* source_ = nullptr;

explicit stop_token(stop_source* source) noexcept : source_{ source } {
  }

public:
  stop_token(const stop_token&) noexcept = default;
  stop_token& operator=(const stop_token&) noexcept = default;

bool stop_requested() const noexcept;
};

// define stop_source, then:

inline bool stop_token::stop_requested() const noexcept {
  return source_->stop_requested();
}
```

---

# Comments

- the point of the `stop_source` is to allow a holder to check if it needs to
  stop without being able to request a stop
- forward declarations sometimes abused to gain compilation times at the cost
  of code maintenance difficulties, but this is a genuine case where forward
  declaration is required to break the circular dependency between: the
  `stop_source` that needs to return a `stop_token` AND the `stop_token` that
  needs to check the contents of the `stop_source`

But can we avoid polling?

---

# Stop callback usage

```cpp
TEST(stop_util_trivial)
{
  stop_source source;
  stop_token token = source.get_token();

bool called{ false };
  coro_st::stop_callback callback{ token, [&called]() noexcept {
    called = true;
  }};

ASSERT_FALSE(called);

ASSERT_TRUE(source.request_stop());

ASSERT_TRUE(called);
}
```

---

# Stop callback

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250603-2-box" width="100%" viewBox="0 0 800 300">
  <style>
    #svg20250603-2-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250603-2-t1 {
      font-family: sans-serif;
      font-size: 16px;
      dominant-baseline: middle;
    }
    .svg20250603-2-l1 {
      stroke: #000000;
      stroke-width: 2;
      fill: none;
    }
    .svg20250603-2-l2 {
      stroke: #000000;
      stroke-dasharray: 5;
      stroke-width: 2;
      fill: none;
    }
    .svg20250603-2-task_white {
      stroke: #000000;
      stroke-width: 4;
      fill: #ffffff;
    }
    .svg20250603-2-task_orange {
      stroke: #000000;
      stroke-width: 4;
      fill: #f5bb00;
    }
    .svg20250603-2-task_pink {
      stroke: #000000;
      stroke-width: 4;
      fill: #ff36ab;
    }
    .svg20250603-2-task_red {
      stroke: #000000;
      stroke-width: 4;
      fill: #ee6055;
    }
  </style>
  <defs>
    <marker id="svg20250603-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"/>
    </marker>
  </defs>
  <rect x="30" y="10" width="100" height="100" class="svg20250603-2-task_white"/>
  <path class="svg20250603-2-l1" d="M 80 30 v 65 h -60" marker-end="url(#svg20250603-2-arrow)"/>
  <rect x="180" y="40" width="100" height="30" class="svg20250603-2-task_white"/>
  <text class="svg20250603-2-t1" x="190" y="55">next</text>
  <rect x="180" y="70" width="100" height="30" class="svg20250603-2-task_white"/>
  <text class="svg20250603-2-t1" x="190" y="85">prev</text>
  <rect x="180" y="100" width="100" height="60" class="svg20250603-2-task_orange"/>
  <text class="svg20250603-2-t1" x="190" y="130">callback</text>
  <path class="svg20250603-2-l1" d="M 180 100 l 100 -30"/>
  <rect x="330" y="40" width="100" height="30" class="svg20250603-2-task_white"/>
  <text class="svg20250603-2-t1" x="340" y="55">next</text>
  <rect x="330" y="70" width="100" height="30" class="svg20250603-2-task_white"/>
  <text class="svg20250603-2-t1" x="340" y="85">prev</text>
  <rect x="330" y="100" width="100" height="60" class="svg20250603-2-task_pink"/>
  <text class="svg20250603-2-t1" x="340" y="130">callback</text>
  <path class="svg20250603-2-l1" d="M 330 70 l 100 -30"/>
  <rect x="480" y="130" width="100" height="30" class="svg20250603-2-task_red"/>
  <text class="svg20250603-2-t1" x="490" y="145">stop</text>
  <rect x="480" y="160" width="100" height="30" class="svg20250603-2-task_white"/>
  <text class="svg20250603-2-t1" x="490" y="175">head</text>
  <rect x="480" y="190" width="100" height="30" class="svg20250603-2-task_white"/>
  <text class="svg20250603-2-t1" x="490" y="205">tail</text>
  <path class="svg20250603-2-l2" d="M 80 40 h 92" marker-end="url(#svg20250603-2-arrow)"/>
  <path class="svg20250603-2-l1" d="M 280 55 h 42" marker-end="url(#svg20250603-2-arrow)"/>
  <path class="svg20250603-2-l1" d="M 330 85 h -42" marker-end="url(#svg20250603-2-arrow)"/>
  <path class="svg20250603-2-l1" d="M 480 175 h -250 v -7" marker-end="url(#svg20250603-2-arrow)"/>
  <path class="svg20250603-2-l1" d="M 480 205 h -25 v -120 h -17" marker-end="url(#svg20250603-2-arrow)"/>
  <text class="svg20250603-2-t1" x="140" y="25">stop_callback</text>
  <rect x="630" y="10" width="100" height="150" class="svg20250603-2-task_white"/>
  <rect x="630" y="160" width="100" height="80" class="svg20250603-2-task_orange"/>
  <rect x="630" y="240" width="100" height="20" class="svg20250603-2-task_pink"/>
  <rect x="630" y="260" width="100" height="30" class="svg20250603-2-task_white"/>
  <path class="svg20250603-2-l1" d="M 680 30 v 240" marker-end="url(#svg20250603-2-arrow)"/>
  <path class="svg20250603-2-l2" d="M 680 145 h -92" marker-end="url(#svg20250603-2-arrow)"/>
  <text class="svg20250603-2-t1" x="500" y="115">source.request_stop()</text>
  <rect x="30" y="220" width="100" height="50" class="svg20250603-2-task_white"/>
  <path class="svg20250603-2-l2" d="M 630 230 h -492" marker-end="url(#svg20250603-2-arrow)"/>
  <path class="svg20250603-2-l1" d="M 20 230 h 60 v 22" marker-end="url(#svg20250603-2-arrow)"/>
</svg>
</div>

- the `stop_callback` gets to the list header via the `stop_token`
- callback is invoked by the caller of `stop_source.request_stop()`

---
# Stop callback - late

<div align="center">
<svg xmlns="http://www.w3.org/2000/svg" id="svg20250603-3-box" width="100%" viewBox="0 0 800 300">
  <style>
    #svg20250603-3-box {
      border: 1px solid #e8e8e8;
      background-color: #f5f5f5;
    }
    .svg20250603-3-t1 {
      font-family: sans-serif;
      font-size: 16px;
      dominant-baseline: middle;
    }
    .svg20250603-3-l1 {
      stroke: #000000;
      stroke-width: 2;
      fill: none;
    }
    .svg20250603-3-l2 {
      stroke: #000000;
      stroke-dasharray: 5;
      stroke-width: 2;
      fill: none;
    }
    .svg20250603-3-task_white {
      stroke: #000000;
      stroke-width: 4;
      fill: #ffffff;
    }
    .svg20250603-3-task_orange {
      stroke: #000000;
      stroke-width: 4;
      fill: #f5bb00;
    }
    .svg20250603-3-task_pink {
      stroke: #000000;
      stroke-width: 4;
      fill: #ff36ab;
    }
    .svg20250603-3-task_red {
      stroke: #000000;
      stroke-width: 4;
      fill: #ee6055;
    }
  </style>
  <defs>
    <marker id="svg20250603-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"/>
    </marker>
  </defs>
  <rect x="30" y="10" width="100" height="150" class="svg20250603-3-task_white"/>
  <rect x="30" y="160" width="100" height="80" class="svg20250603-3-task_orange"/>
  <rect x="30" y="240" width="100" height="30" class="svg20250603-3-task_white"/>
  <path class="svg20250603-3-l1" d="M 80 30 v 222" marker-end="url(#svg20250603-3-arrow)"/>
  <rect x="480" y="50" width="100" height="30" class="svg20250603-3-task_red"/>
  <text class="svg20250603-3-t1" x="490" y="65">stop</text>
  <rect x="480" y="80" width="100" height="30" class="svg20250603-3-task_white"/>
  <text class="svg20250603-3-t1" x="490" y="95">head</text>
  <rect x="480" y="110" width="100" height="30" class="svg20250603-3-task_white"/>
  <text class="svg20250603-3-t1" x="490" y="125">tail</text>
  <path class="svg20250603-3-l1" d="M 480 110 l 100 -30"/>
  <path class="svg20250603-3-l1" d="M 480 140 l 100 -30"/>
  <path class="svg20250603-3-l2" d="M 80 150 h 92" marker-end="url(#svg20250603-3-arrow)"/>
  <text class="svg20250603-3-t1" x="140" y="135">stop_callback</text>
  <rect x="180" y="150" width="100" height="30" class="svg20250603-3-task_white"/>
  <text class="svg20250603-3-t1" x="190" y="165">next</text>
  <rect x="180" y="180" width="100" height="30" class="svg20250603-3-task_white"/>
  <text class="svg20250603-3-t1" x="190" y="195">prev</text>
  <rect x="180" y="210" width="100" height="60" class="svg20250603-3-task_white"/>
  <text class="svg20250603-3-t1" x="190" y="240">callback</text>
  <path class="svg20250603-3-l1" d="M 180 180 l 100 -30"/>
  <path class="svg20250603-3-l1" d="M 180 210 l 100 -30"/>
  <path class="svg20250603-3-l1" d="M 180 270 l 100 -60"/>
  <rect x="630" y="10" width="100" height="280" class="svg20250603-3-task_white"/>
  <path class="svg20250603-3-l1" d="M 680 30 v 240" marker-end="url(#svg20250603-3-arrow)"/>
  <path class="svg20250603-3-l2" d="M 680 65 h -92" marker-end="url(#svg20250603-3-arrow)"/>
  <text class="svg20250603-3-t1" x="500" y="35">source.request_stop()</text>
  <path class="svg20250603-3-l2" d="M 280 165 h 100 v -90 h 92" marker-end="url(#svg20250603-3-arrow)"/>
</svg>
</div>

- callback is invoked by constructor of `stop_callback`

---

# The intrusive list

```cpp
struct stop_list_node {
  stop_list_node* next{ nullptr };
  stop_list_node* prev{ nullptr };
  callback cb{};

stop_list_node() noexcept = default;

stop_list_node(const stop_list_node&) = delete;
  stop_list_node& operator=(const stop_list_node&) = delete;
};

using stop_list = intrusive_list<stop_list_node,
                    &stop_list_node::next, &stop_list_node::prev>;
```

---

# Stop source members

```cpp
class stop_source
{
  template <typename Fn>
  friend class stop_callback;

bool stop_{ false };
  stop_list callbacks_{};
```

---

# Stop source request_stop

```cpp
  bool request_stop() noexcept {
    if (stop_) {
      return false;
    }
    stop_ = true;
    while(true) {
      // handle case where callbacks remove other callbacks
      stop_list_node* node = callbacks_.pop_front();
      if (node == nullptr) {
        break;
      }
      callback copy_cb = node->cb;
      // stop_callback destructor will not invoke
      node->cb = callback{};
      copy_cb.invoke();
    }
    return true;
  }
```

---

# Stop callback constructor

```cpp
template<>
class stop_callback<callback>
{
  stop_source* source_ = nullptr;
  stop_list_node node_;
public:
  stop_callback(stop_token token, callback fn) noexcept :
    source_{ token.source_ }
  {
    assert(source_ != nullptr);
    assert(fn.is_callable());
    if (source_->stop_requested()) {
      fn();
    }
    else {
      node_.cb = fn;
      source_->callbacks_.push_back(&node_);
    }
  }
```

---

# Stop callback destructor

```cpp
  ~stop_callback() {
    // handle case where it was not stopped
    // also handle cases where it was already called
    if (node_.cb.is_callable()) {
      source_->callbacks_.remove(&node_);
    }
  }
}; // stop_callback
```

---

# Care

Needs to be taken to handle cases:

- stop_callback is destructed and request_stop was not called: don't call the
  callback
- request_stop iterates through the list of stop_callback nodes, but the list
  content changes as the callbacks are called (e.g. a callback might remove
  other nodes as part of the cancellation work it does)
- request_stop was called before the stop_callback is constructed
  stopped
- only shown single threaded code, more complexity is required to handle
  multi-threading (e.g. a stop_callback destructor runs around the time when
  the callback is called due to a request_stop: the destructor needs to wait)
- the stop_callback nodes should not move
- the stop_source should not move (e.g. our stop_token has a reference to it)

---

# `std::stop_source` issues

```cpp
stop_source();
explicit stop_source( std::nostopstate_t nss ) noexcept;
stop_source( const stop_source& other ) noexcept;
stop_source( stop_source&& other ) noexcept;
```

- WAIT, WHAT?
  - why is the default constructor not `noexcept`?
  - what's `nostopstate_t`?
  - how is copy `noexcept`?
  - how can it be moved?
- also what's `stop_possible()`?

---

# `std::stop_source` design

- the design is one that was suitable for std::jthread
- it involves allocating the stop_source state hence:
  - constructor of stop_source can throw bad::alloc
  - copy of stop_source is noexcept: it increments reference count to
    stop_source state
- e.g. a small allocation is not a big problem when a thread is started

- Bummer! We had great plans, now what?

---

# `std::inplace_stop_...`

- proposal derived from work on senders/receivers introduced in C++26 the
  std::inplace_stop_source, std::inplace_stop_token and
  std::inplace_stop_callback
- it also comes with a concept that is meant to cover the `std::stop_source`
  oddities e.g. `stop_possible()` (which is hardcoded to `true` for
  `std::inplace_stop_source`
- there is also support for getting the associated stop_callback type to a
  stop_token type (via `callback_type`)

---

# Last words

- There might still be value in a single threaded `stop_...` version for some
  T1 threading model
- We used a `callback` (two pointers) in the node of our `stop_callback`:
  - additional space used in the node
  - but the level of indirection of calling the cancellation might be reduced
  - more research is needed if that makes sense

---

# Questions?