Repository navigation
actor: exempt driver waits, add AllowAwaitInTurn, drop Ask outbox mode - #1380
Merged
Merged
Conversation
Roasbeef
force-pushed
the
actor-await-policy-enforce
branch
from
October 3, 2026 22:19
d914f7a to
8a58718
Compare
Roasbeef
force-pushed
the
actor-await-policy-enforce
branch
from
October 5, 2026 23:50
8a58718 to
dfa857e
Compare
Roasbeef
force-pushed
the
actor-await-policy-enforce
branch
from
October 5, 2026 23:59
dfa857e to
053a330
Compare
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
force-pushed
the
actor-await-policy-enforce
branch
from
October 6, 2026 00:33
053a330 to
0061d81
Compare
Roasbeef
marked this pull request as ready for review
October 6, 2026 01:10
litbot-9000
approved these changes
Oct 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.Receiveawaits its own driver's future, which is a wait on a goroutine the machine owns, not on another actor's mailbox.AskEventnow returns a small wrapper whoseAwaitgoes throughOnComplete, which already runs outside the policy. The future is untargeted, so it registers no wait-graph edge either. This covers every behavior that awaits anAskEventresult 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 bybeginTurn, 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 getsErrWaitCycleinstead 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, andStateMachine.Startapplies it, which fixes every FSM start path in one place.Removing the Ask outbox mode
RoutedOutboxEvent.Dispatchin Ask delivery mode awaited a routerAskinside the receive turn. Moving it to a non-parking form would have changed the documented sequencing and theDispatcherror contract, and nothing in the repo or its tests used it. SoDeliveryModeAsk,NewAskOutboxEvent, theDeliveryModetype and the Ask branch are removed. Tell delivery is unchanged.PROTOFSM_ACTOR_GUIDE.mdnow 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/actorand one insdk/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.