Skip to content

actor: exempt driver waits, add AllowAwaitInTurn, drop Ask outbox mode - #1380

Merged
Roasbeef merged 3 commits into
round-board-askthenfrom
actor-await-policy-enforce
Oct 6, 2026
Merged

Roasbeef merged 3 commits into
round-board-askthenfrom
actor-await-policy-enforce

Conversation

@Roasbeef

@Roasbeef Roasbeef commented Oct 3, 2026

Copy link
Copy Markdown
Member

In this PR, we add the exemptions the await-in-turn policy needs before its default can move from Warn to Error, and remove an outbox delivery mode that could not be made safe. It is stacked on the round boarding PR, on top of #1371 to #1373.

Exemptions

Two kinds of wait are safe by construction and would be false positives under AwaitInTurnError.

A protofsm StateMachine.Receive awaits its own driver's future, which is a wait on a goroutine the machine owns, not on another actor's mailbox. AskEvent now returns a small wrapper whose Await goes through OnComplete, which already runs outside the policy. The future is untargeted, so it registers no wait-graph edge either. This covers every behavior that awaits an AskEvent result in its own turn.

For a reviewed one-off, actor.AllowAwaitInTurn(ctx, reason) marks a derived context as exempt. An empty reason is ignored so every exemption carries an explanation. The marker is cleared by beginTurn, so it does not ride along on an Ask into the callee's turn, and an exempt wait still registers with the cycle detector, so a callee that does call back gets ErrWaitCycle instead of hanging.

An FSM started from a receive turn used to keep that turn's marker on its driver goroutine, so the driver's own awaits were treated as in-turn while the starting turn was active. actor.WithoutTurn(ctx) clears the marker, and StateMachine.Start applies it, which fixes every FSM start path in one place.

Removing the Ask outbox mode

RoutedOutboxEvent.Dispatch in Ask delivery mode awaited a router Ask inside the receive turn. Moving it to a non-parking form would have changed the documented sequencing and the Dispatch error contract, and nothing in the repo or its tests used it. So DeliveryModeAsk, NewAskOutboxEvent, the DeliveryMode type and the Ask branch are removed. Tell delivery is unchanged. PROTOFSM_ACTOR_GUIDE.md now shows persistence as a Tell followed by a result event handled in a later state.

What this does not do

The default stays at Warn. Flipping it to Error today fails tests in chainsource, unroll, vtxo, baselib/actor and one in sdk/ark, because many in-turn waits remain. Those are audited and tracked separately, and the lint PR above this one adds a baseline so no new ones appear in the meantime.

@Roasbeef
Roasbeef added this pull request to stack #1378 October 3, 2026 01:17
@Roasbeef
Roasbeef force-pushed the actor-await-policy-enforce branch from d914f7a to 8a58718 Compare October 3, 2026 22:19
@Roasbeef
Roasbeef force-pushed the actor-await-policy-enforce branch from 8a58718 to dfa857e Compare October 5, 2026 23:50
@Roasbeef
Roasbeef force-pushed the actor-await-policy-enforce branch from dfa857e to 053a330 Compare October 5, 2026 23:59
In this commit, we add the two exemptions that let AwaitInTurnError
become the default without refusing waits that are safe.

A protofsm state machine is driven by its own goroutine. When a
behavior hosts the machine and awaits the future from AskEvent, the
caller hands work to its own helper and is not waiting on another
actor's mailbox. AskEvent now returns a future whose Await waits
through OnComplete, which already runs outside the await-in-turn
policy. This exempts StateMachine.Receive and every behavior that
awaits an AskEvent future by construction, with no new API in the
actor package. The future is untargeted, so the wait registers no edge
and cannot form a false cycle.

For a bounded wait whose callee provably never calls back, we add
AllowAwaitInTurn(ctx, reason). It marks one derived context as
exempt from the policy. An empty reason is ignored so the exemption
always carries an explanation. beginTurn clears the marker, so it
does not ride along on an Ask into the callee's own turn. The wait
still registers with the cycle detector, so a callee that does call
back is reported as ErrWaitCycle instead of hanging.
In this commit, we remove DeliveryModeAsk, NewAskOutboxEvent and the
Ask branch of RoutedOutboxEvent.Dispatch. With a single mode left, we
also drop the DeliveryMode type and the mode field.

The Ask branch awaited the target's reply inside the state machine's
receive turn. That parks the machine's whole mailbox and deadlocks
when the target is, in turn, waiting on the machine. It also cannot
be made non-parking without changing what Dispatch returns, because
the Ask error was returned from Receive and reported to the error
reporter. Nothing in the tree used it.

A transition that needs an answer should have the target send a result
event back to the machine and move to a waiting state. The protofsm
actor guide now describes that pattern instead of recommending Ask for
persistence.
In this commit, we document the two exemptions from the await-in-turn
policy in the actor and protofsm package docs and the actor README.

AllowAwaitInTurn is the per-call opt-out for a bounded wait whose
callee never calls back, and it still registers with the wait cycle
detector. The AskEvent driver future is exempt by construction, since
the state machine's driver goroutine belongs to the hosting actor.
The protofsm docs also record that outbox delivery is Tell only, with
results returning to the machine as events.
@Roasbeef
Roasbeef force-pushed the actor-await-policy-enforce branch from 053a330 to 0061d81 Compare October 6, 2026 00:33
@Roasbeef
Roasbeef marked this pull request as ready for review October 6, 2026 01:10
@Roasbeef
Roasbeef merged commit 2939a69 into main Oct 6, 2026
36 of 38 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants