Skip to content

Commit d22be8b

Browse files
committed
docs(invoke): clarify independent vs grouped invokes behavior
Explain that passing a list creates independent invocations where the first done.invoke triggers the transition and cancels the rest. Point users to invoke_group when all callables must complete before transitioning.
1 parent 543bc71 commit d22be8b

2 files changed

Lines changed: 13 additions & 7 deletions

File tree

docs/invoke.md

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -372,10 +372,13 @@ True
372372

373373
### Independent invokes (one event each)
374374

375-
Pass a list to run multiple handlers concurrently. Each handler gets its own
376-
`done.invoke.<state>.<id>` event — the **first** one to complete triggers the
377-
`done_invoke_<state>` transition (the remaining events are ignored if the state
378-
was already exited):
375+
Pass a list to run multiple handlers concurrently. Each handler is an independent
376+
invocation that sends its own `done.invoke.<state>.<id>` completion event.
377+
378+
This means that the **first** handler to complete triggers the `done_invoke_<state>`
379+
transition, which exits the owning state and **cancels all remaining invocations**.
380+
If you need all handlers to complete before transitioning, use
381+
{func}`~statemachine.invoke.invoke_group` instead (see below).
379382

380383
```py
381384
>>> file_a = Path(tempfile.mktemp(suffix=".txt"))
@@ -411,7 +414,8 @@ separate transition.
411414

412415
Use {func}`~statemachine.invoke.invoke_group` to run multiple callables concurrently
413416
and wait for **all** of them to complete before sending a single `done.invoke` event.
414-
The `data` is a list of results in the same order as the input callables:
417+
Unlike independent invokes (list), the transition only fires after every callable
418+
finishes, and the `data` is a list of results in the same order as the input callables:
415419

416420
```py
417421
>>> from statemachine.invoke import invoke_group

docs/releases/3.0.0.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,10 @@ True
4444

4545
```
4646

47-
Use {func}`~statemachine.invoke.invoke_group` to run multiple callables concurrently
48-
and wait for all results:
47+
Passing a list of callables (`invoke=[a, b]`) creates independent invocations — each
48+
sends its own `done.invoke` event, so the first to complete triggers the transition and
49+
cancels the rest. Use {func}`~statemachine.invoke.invoke_group` when you need all
50+
callables to complete before transitioning:
4951

5052
```py
5153
>>> from statemachine.invoke import invoke_group

0 commit comments

Comments
 (0)