Skip to content

Commit 8eefb40

Browse files
ispetersclaude
andcommitted
Add a phase-based when_all that stops its children together
`when_all` is the first phase-based algorithm whose children run at once, and the first that needs a stop source of its own: when one child fails or stops, the others must be asked to stop, and the receiver's stop requests must reach them too. Those lifetimes are easy to get wrong, since a child can complete, and so end the operation, from inside the very `request_stop` that asked it to, so they go in the machinery. A `join_scope` holds the stop source, the callback forwarding the receiver's stop requests to it, and a count of the children still running. A child that fails or stops arrives with `stop_and_arrive()`, which requests stop before counting the child out, so no child can end the scope from inside its own `request_stop`. The last to arrive drops the forwarding callback, waiting for one running on another thread, before the operation finishes. Under `eager_teardown`, finishing ends the phase, stop source included, perhaps from inside the source's `request_stop` when the receiver asked to stop, which stdexec's `inplace_stop_source` allows since NVIDIA#1889. `attempt(fn)` returns what `fn` threw, so storing a child's values or error needs no `try`. `when_all` holds one phase with a child per sender, connected on entry, each seeing the receiver's environment with the phase's stop token in place of the receiver's. The children's values and the first error stay in the phase until the last child completes, so `when_all` sends decayed copies under either ending. Like stdexec's, it accepts children that send at most one set of values. The demo adds `when_all` to the cost table: it moves values less often than stdexec's except under `split_sender`, and takes 64 to 72 more bytes, mostly an error slot for the `std::exception_ptr` every algorithm here declares, the root's pointer and the bytes recording live phases. Section 15 shows a child's error, and a stop request from the receiver, reaching the other children through the phase's token. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent cb50695 commit 8eefb40

4 files changed

Lines changed: 576 additions & 6 deletions

File tree

‎examples/frames/README.md‎

Lines changed: 43 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -66,14 +66,17 @@ to `outer`.
6666

6767
## Part two: operation states as sequences of phases
6868

69-
`just.hpp`, `then.hpp`, `let_value.hpp`, `sequence.hpp` and `repeat_n.hpp`
70-
reimplement `just`, `then`, `let_value`, a binary `sequence` and `repeat_n`
71-
with operation states that hold one *phase* at a time, written against the
69+
`just.hpp`, `then.hpp`, `let_value.hpp`, `sequence.hpp`, `repeat_n.hpp` and
70+
`when_all.hpp` reimplement `just`, `then`, `let_value`, a binary `sequence`,
71+
`repeat_n` and `when_all` with operation states that hold one *phase* at a
72+
time, written against the
7273
machinery in `typestate.hpp`. The aim is a standard way of expressing an
7374
operation's states and transitions, so that lifetimes are correct by
7475
construction, at no cost relative to the established approach. The machinery
75-
is where the complexity lives, in about 1400 lines; each algorithm takes 125
76-
to 180, about a fifth of them completion signatures.
76+
is where the complexity lives, in about 1600 lines; each algorithm takes 125
77+
to 180, about a fifth of them completion signatures, except `when_all`,
78+
whose 395 include about 120 working out its completion signatures and the
79+
types it stores.
7780

7881
- **`phased<Rcvr, Parts, Carried, Phases...>`** holds the operation's
7982
receiver, a *carried* region that lives as long as the operation, and
@@ -100,6 +103,15 @@ to 180, about a fifth of them completion signatures.
100103
worked out. Keyed by the tag, it can differ per child, as a fork of
101104
automatic storage would need. `env_with<Query, Value, Env>` replaces one
102105
query and carries over the rest, policies included.
106+
- **Children that run at once and stop together** share a `join_scope`: a
107+
stop source whose token their environments carry, a callback that forwards
108+
the receiver's stop requests to it from `open()` until the last child
109+
arrives, and a count of the children still running. `when_all` holds one
110+
in its single phase. A child that fails or stops arrives with
111+
`stop_and_arrive()`, which requests stop before counting the child out, so
112+
no child can end the scope during its own `request_stop`. The last to
113+
arrive (`arrive()` returns `true`) drops the forwarding callback, waiting
114+
for one running on another thread, before the operation finishes.
103115
- **A transition** runs inside the live phase's completion. `prepare` sees
104116
the dying phase and the completion's arguments while they're alive; it may
105117
store into the carried region, and returns what the next phase's
@@ -208,6 +220,7 @@ which is every level's carried data at once.
208220
| 12 | `repeat_n`: iteration counts, a failing iteration, and copies against `exec::repeat_n`. |
209221
| 13 | With `-fsanitize=address -DFRAMES_SHOW_USE_AFTER_FINISH`: a child that touches its own state after completing, reported by AddressSanitizer. |
210222
| 14 | When `let_value`'s values are destroyed, under each layout and both endings. |
223+
| 15 | `when_all` giving its children its own stop token: a child's error, and the receiver's stop request, reaching the other children. |
211224

212225
Costs (x86-64; GCC 13 and Clang 18, with libstdc++ or libc++, agree except
213226
where noted; "eager+start" is `eager_teardown` with `start_entry`, and
@@ -232,6 +245,7 @@ let_value(just(v), fn) 552 6 (0) 568 5 (0) 568 4 (0) 568
232245
... scoped_layout 568 5 (0) 568 4 (0) 560 5 (0) 536 7 (0)
233246
sequence(s, just(v))* 560 9 (0) 568 5 (0) 568 3 (0) 552 5 (0) 552 8 (0)
234247
then(just(v), fn) 24 7 (0) 40 7 (0) 40 5 (0) 32 7 (0) 24 9 (0)
248+
when_all of two just(v) 1072 14 (0) 1144 12 (0) 1144 8 (0) 1136 12 (0) 1136 16 (0)
235249
236250
* stdexec moves 8 (0) with Clang
237251
```
@@ -254,6 +268,14 @@ the child's address instead of stored (P3425, worded for C++26 by P3986 as
254268
`inlinable_receiver`) would turn that walk into constant offsets, and remove
255269
the receivers' own pointers too.
256270

271+
`when_all` keeps its children's values in its phase until the last child
272+
completes, as stdexec's does, and moves them less often except under
273+
`split_sender`. Its extra bytes are mostly an error slot, since like every
274+
algorithm here it declares `set_error_t(std::exception_ptr)` where stdexec's
275+
keeps no room for errors its children can't send (16 bytes), and the root's
276+
pointer and the bytes recording `when_all`'s and each `just`'s live phase,
277+
with their padding (32).
278+
257279
`split_sender` trades the other way. Each operation moves in the data it
258280
uses, so a value moves once per level rather than once in all, but the data
259281
lives where its phase does: `overlapped_layout` saves bytes again, and
@@ -296,6 +318,22 @@ What else it taught:
296318
typestate senders pays this once, at the root, since the operations below
297319
bind their children; under `split_sender`, each level connects its
298320
children through `connect`.
321+
- **Stop requests end operations from inside their own callbacks.** A
322+
child that completes from its stop callback can make its parent change
323+
phase (`let_value`'s second child then registers its callback with a
324+
source that's in the middle of `request_stop`) or finish, and under
325+
`eager_teardown` end the phase holding the child, its callback and, in
326+
`when_all`, the stop source whose `request_stop` is running. That's
327+
allowed: a stop callback may be destroyed from its own invocation, and
328+
since #1889 stdexec's `inplace_stop_source` may be destroyed by one of its
329+
own callbacks. What it asks of children is the usual rule, applied
330+
strictly: since eager teardown ends a child's phase before the child's
331+
`start` or stop callback returns, a child that writes to itself after
332+
completing is caught every time, not only when its parent happens to
333+
destroy the operation. A child that registers its stop callback with
334+
`std::optional::emplace` and completes from the callback is one such: when
335+
stop has already been requested, the callback runs inside `emplace`, which
336+
sets its flag afterwards.
299337
- **Completion signatures are still much of the work.** About 160 of
300338
`typestate.hpp`'s lines, and 20 to 30 of each algorithm's, compute them,
301339
and phases don't help with that; every algorithm here except `just`

‎examples/frames/demo.cpp‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
#include "repeat_n.hpp"
2020
#include "sequence.hpp"
2121
#include "then.hpp"
22+
#include "when_all.hpp"
2223

2324
#include <exec/repeat_n.hpp>
2425
#include <exec/sequence.hpp>
@@ -552,6 +553,13 @@ int main()
552553
ts::carried_layout(),
553554
[&] { return ts::then(ts::just(1), plus_one); },
554555
[&] { return ts::then(ts::just(counted()), then_fn); });
556+
cost_row(
557+
"when_all of two just(v)",
558+
opstate_size<decltype(ex::when_all(ex::just(big{}), ex::just(big{})))>,
559+
count(ex::when_all(ex::just(counted()), ex::just(counted()))),
560+
ts::carried_layout(),
561+
[] { return ts::when_all(ts::just(big{}), ts::just(big{})); },
562+
[] { return ts::when_all(ts::just(counted()), ts::just(counted())); });
555563
}
556564

557565
#if !STDEXEC_NO_STDCPP_EXCEPTIONS()
@@ -753,4 +761,42 @@ int main()
753761
trace(forward(), ts::overlapped_layout(), "forward, overlapped:");
754762
trace(forward(), ts::scoped_layout(), "forward, scoped:");
755763
}
764+
765+
{
766+
section("15. when_all stops its children together");
767+
// when_all's phase holds a stop source of its own, and its children see
768+
// its token in place of the receiver's, with the rest of the receiver's
769+
// environment (the policies, say) carried over. A child's error stops
770+
// the others, and so does a stop request from the receiver, which
771+
// reaches the phase's source once when_all starts. Each child here
772+
// reads its token as it starts.
773+
auto child = [](char const * name)
774+
{
775+
return ex::read_env(ex::get_stop_token)
776+
| ex::then(
777+
[name](auto token)
778+
{ std::printf(" %s %s;", name, token.stop_requested() ? "stopped" : "running"); });
779+
};
780+
std::printf(" a child's error: ");
781+
ex::sync_wait(ts::when_all(child("first"), ex::just_error(1), child("third"))
782+
| ex::upon_error(
783+
[]<class E>(E const & e)
784+
{
785+
if constexpr (std::is_same_v<E, int>)
786+
{
787+
std::printf(" error %d\n", e);
788+
}
789+
else
790+
{
791+
std::printf(" exception\n");
792+
}
793+
}));
794+
795+
ex::inplace_stop_source source;
796+
source.request_stop();
797+
std::printf(" the receiver's stop: ");
798+
ex::sync_wait(ex::write_env(ts::when_all(child("first"), child("second")),
799+
ex::prop{ex::get_stop_token, source.get_token()})
800+
| ex::then([] { std::printf(" values\n"); }));
801+
}
756802
}

‎examples/frames/typestate.hpp‎

Lines changed: 92 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,8 @@
2727
* phase is destroyed with the operation state.
2828
*
2929
* This header holds that machinery; the algorithms written against it are
30-
* in just.hpp, then.hpp, let_value.hpp, sequence.hpp and repeat_n.hpp.
30+
* in just.hpp, then.hpp, let_value.hpp, sequence.hpp, repeat_n.hpp and
31+
* when_all.hpp.
3132
*
3233
* Prototype simplifications: senders are connected as rvalues only, every
3334
* algorithm except just conservatively declares
@@ -39,12 +40,14 @@
3940
#include <stdexec/execution.hpp>
4041

4142
#include <algorithm>
43+
#include <atomic>
4244
#include <concepts>
4345
#include <cstddef>
4446
#include <exception>
4547
#include <functional>
4648
#include <memory>
4749
#include <new>
50+
#include <optional>
4851
#include <tuple>
4952
#include <type_traits>
5053
#include <utility>
@@ -1352,6 +1355,94 @@ namespace frames::typestate
13521355
Env env;
13531356
};
13541357

1358+
// Children of one phase that run at once and stop together: a stop source
1359+
// of their own, which a stop request from the operation's environment
1360+
// also reaches, and a count of the children still running. The phase
1361+
// holds it before its children, whose environments carry token(), and
1362+
// opens it before starting them. Each child's completion arrives once:
1363+
// with arrive(), or with stop_and_arrive() to stop the others first. The
1364+
// one that returns true is the last; by then the operation's environment
1365+
// no longer reaches the scope, and nothing else will touch the phase, so
1366+
// the operation may end it.
1367+
//
1368+
// A stop request from the environment can make the last child complete
1369+
// inside this scope's request_stop, and so end the scope there;
1370+
// stdexec's inplace_stop_source allows its own callbacks to destroy it.
1371+
template <class Env>
1372+
class join_scope
1373+
{
1374+
struct forward_stop
1375+
{
1376+
ex::inplace_stop_source* source;
1377+
1378+
void operator()() const noexcept
1379+
{
1380+
source->request_stop();
1381+
}
1382+
};
1383+
1384+
using callback_t = ex::stop_callback_for_t<ex::stop_token_of_t<Env const &>, forward_stop>;
1385+
1386+
public:
1387+
explicit join_scope(std::size_t count) noexcept
1388+
: count_(count)
1389+
{}
1390+
1391+
join_scope(join_scope&&) = delete;
1392+
1393+
[[nodiscard]]
1394+
auto token() const noexcept -> ex::inplace_stop_token
1395+
{
1396+
return source_.get_token();
1397+
}
1398+
1399+
void open(Env const & env) noexcept
1400+
{
1401+
forward_.emplace(ex::get_stop_token(env), forward_stop{&source_});
1402+
}
1403+
1404+
// A child that arrives this way never ends the scope during its own
1405+
// request_stop: until it arrives, the count includes it.
1406+
[[nodiscard]]
1407+
auto stop_and_arrive() noexcept -> bool
1408+
{
1409+
source_.request_stop();
1410+
return arrive();
1411+
}
1412+
1413+
[[nodiscard]]
1414+
auto arrive() noexcept -> bool
1415+
{
1416+
if (count_.fetch_sub(1, std::memory_order_acq_rel) != 1)
1417+
{
1418+
return false;
1419+
}
1420+
// Waits for a forwarded request running on another thread.
1421+
forward_.reset();
1422+
return true;
1423+
}
1424+
1425+
private:
1426+
ex::inplace_stop_source source_;
1427+
std::atomic<std::size_t> count_;
1428+
std::optional<callback_t> forward_;
1429+
};
1430+
1431+
// Calls fn(), returning what it threw, if anything.
1432+
template <class Fn>
1433+
auto attempt(Fn fn) noexcept -> std::exception_ptr
1434+
{
1435+
STDEXEC_TRY
1436+
{
1437+
fn();
1438+
return nullptr;
1439+
}
1440+
STDEXEC_CATCH_ALL
1441+
{
1442+
return std::current_exception();
1443+
}
1444+
}
1445+
13551446
// The receiver a phase's child completes through. `Tag` names the phase,
13561447
// or the child when a phase runs several; `Child`, if not void, is the
13571448
// child sender the phase binds (const if it binds without consuming).

0 commit comments

Comments
 (0)