Skip to content

Make the queue of the session thread the turn of execute, hardening it against failing waiters and double resumption, fixes #235 - #266

Merged
morisil merged 5 commits into
mainfrom
issue-235-harden-turn
Nov 12, 2026
Merged

morisil merged 5 commits into
mainfrom
issue-235-harden-turn

Conversation

@morisil

@morisil morisil commented Nov 12, 2026

Copy link
Copy Markdown
Member

Fixes #235

#260 (fix of #239) also changes ScriptSession.kt and ScriptSessionTest.kt, in other places — whichever merges second may need a small rebase.

Summary

The issue's long-term route: the single-thread executor's queue is the turn, the mutex is gone.

  • Each execute queues its snippet on the session thread at once, as a thin QueuedTurn referencing a Turn; no caller is ever resumed to take its turn, so a waiter's failing dispatcher can neither keep the turn nor replace another caller's failure.
  • One resumption: a Turn resumes its caller at most once — also when a dispatcher, an interceptor, the resume executor or the session executor queues the resumption and then throws.
  • Fatal errors of a dispatcher are not retried; they reach the caller, unwrapped from kotlinx's DispatchException (README).
  • Cancellation: watched by a coroutine suspended on the caller's job (Turn.watch), not a child job — so cancelChildren() of the caller does not drop its snippet, and a completed job completes at once. A waiting caller cancelled resumes at once without its snippet; an already-cancelled caller runs its snippet only on an idle session, as main with a free mutex, so withTimeout { execute } bounds the wait. A cancelled waiter leaves only an empty placeholder queued (GC tests of its snippet, context element and frames).
  • Thread state: Turn is a CoroutineStackFrame, so kotlinx restores the thread context of an undispatched withContext around execute.
  • After a close, each waiter is rejected on the session thread, not behind Dispatchers.Default.
  • The vacuous tests are removed; README, KDoc and CLAUDE.md (the turn, cancellation watching, CoroutineStackFrame) updated.

Review rounds

Run 4: three rounds (an already-cancelled caller waiting behind others, cancelled waiters retained, the caller's cancellation watched by a child job), blocked — see the issue's status comments. Retried with a fresh budget:

  1. Blocking: a thread-local leaked past an undispatched withContext (Turn not a CoroutineStackFrame). Fixed in 7eabf3c.
  2. No blocking findings; ./gradlew build green, ScriptSessionTest 10/10 with --rerun under load; differential measurements against main — thread-context elements on six dispatchers, stack traces with and without debug mode, the watcher over hundreds of executes, FIFO, withTimeoutOrNull loops, close() with waiters — no regression.

Follow-up

🤖 Generated with Claude Code

https://claude.ai/code/session_019VACgNo6bfV3d3xcHLG4QA

@claude

claude Bot commented Nov 12, 2026

Copy link
Copy Markdown

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

xxxxxxxxxxxxx and others added 5 commits November 12, 2026 19:40
…esuming each caller once, fixes #235

The turn of a caller is no longer the lock of a mutex, but its snippet queued at once on the single thread executor
of the session, whose queue orders the callers, so no caller is resumed to take its turn:
a waiting caller is never resumed by the unlocking of another one, nested in it, or on its thread,
so its dispatcher failing there can neither leave it unresumed, holding the turn, nor replace the failure of the other caller,
and a waiting caller rejected by the session closed meanwhile is rejected on the session thread like after its snippet,
so a caller of its own dispatcher no longer waits for Dispatchers.Default behind a caller without one.
The waited / handedOff / isResumedInPlaceByUnlocking / rejection hand-off machinery is gone.

A caller is resumed exactly once, through its Turn, a continuation resuming the caller only the first time,
intercepted anew for each attempt, so a dispatcher, an interceptor, or the resume executor taking the resumption
and throwing after it, like Dispatchers.Default failing to start a worker for the task queued already,
no longer resumes it twice, nor does the session thread taking a snippet and throwing after it.

A caller cancelled while its snippet waits resumes at once without it, like a cancelled waiter of the lock did,
watched by a child job of its job, and is resumed off the session thread when a snippet cancels it,
while a caller cancelled already when calling execute still runs its snippet, cancelled.

A fatal error of a dispatcher is no longer retried from Dispatchers.Default, but passed to the caller at once,
like a fatal error of the snippet, so a retry succeeding no longer swallows it.

The tests of a waiting caller rejected nested in the rejection of the caller it waited for, also while the resume executor fails,
and the two of one started on the thread of that caller, are removed, as no caller waits by suspending any more,
and the other waiting caller tests are described accordingly.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019VACgNo6bfV3d3xcHLG4QA
…drop a cancelled turn's snippet, fixes #235

A caller cancelled already when calling execute was not watched, so it joined the queue, waited for the snippets ahead,
and ran its snippet nevertheless, so withTimeout no longer bounded the wait.
Its turn is now watched as well, so it is rejected with its CancellationException at once, without its snippet,
unless no other turn is queued or running, counted by the session, like the tryLock of the mutex taking a free turn,
so `should evaluate compiled snippet of caller cancelled before the evaluation` still holds.

A cancelled turn left on the queue of the session thread kept its snippet, context and continuation until the snippets ahead ended.
The turn is now the queued runnable itself, and drops its task, its intercepted continuation and its watcher when cancelled,
and the caller's continuation once resumed.

A caller cancelled while its snippet is submitted and rejected by the session closed meanwhile fails with its cancellation,
not the rejection. A fatal error of a dispatcher wrapped by kotlinx.coroutines in its DispatchException is passed to the caller unwrapped,
also on the retry, where one thrown after the caller was resumed is thrown, not only logged.
The in-place resumption when the resume executor fails without queueing the caller is tested again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019VACgNo6bfV3d3xcHLG4QA
…d rethrow what a resumption must not swallow, fixes #235

A turn cancelled while it waits stayed on the queue of the session thread until the snippets ahead ended,
keeping the context of its caller, and its cancellation, which refers to the frames of the caller.
The turn is now queued by a thin runnable, which drops it once the turn is cancelled, or not taken by the thread,
so only that runnable, holding nothing, stays on the queue.

A fatal error of a dispatcher which resumed its caller already, and then threw, is thrown to the resume executor, not swallowed,
and so is a failure of the code of a caller without an interceptor, as before the turn was reworked.
A caller with its job completed already runs its snippet in an idle session, like a cancelled one, as it did with the lock.
The count of the turns is released if watching the cancellation of the caller throws,
the turn initializes its state before intercepting its caller, and the state of a rejected task is merged into the cancelled one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019VACgNo6bfV3d3xcHLG4QA
…fixes #235

The turn watched the cancellation of its caller by a child of the caller's job,
so the caller's own cancelChildren(), like stopping its heartbeat, cancelled the turn
and dropped the snippet of a caller still active, the child showed in its children,
and a completed bare job of the caller waited for it until the turn started.
The turn watches it now by a suspendCancellableCoroutine of a coroutine of the caller's job,
a public API attaching no child, resumed once the turn starts, or is not queued.

Also drops the redundant finish() of a turn cancelled before it starts,
and documents the CancellationException thrown by onSessionThread.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019VACgNo6bfV3d3xcHLG4QA
…w a fatal failure of submitting it, fixes #235

The turn, resumed in place of the caller's continuation, was no CoroutineStackFrame,
so kotlinx.coroutines did not restore the thread state of an undispatched withContext,
leaking its thread context element on the caller's thread after the block.
The turn is a frame now, reading the caller's frame from the caller it still holds, so it retains nothing of a resumed caller.

A caller cancelled while submitting its snippet failed fatally now fails with the fatal error instead of its cancellation,
and a caller of an interceptor returning the continuation it intercepts throws its own failure to the resume executor,
like a caller without an interceptor, instead of it being logged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019VACgNo6bfV3d3xcHLG4QA
@morisil
morisil force-pushed the issue-235-harden-turn branch from 7eabf3c to f73c8f0 Compare November 12, 2026 19:43
@claude

claude Bot commented Nov 12, 2026

Copy link
Copy Markdown

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

@morisil
morisil merged commit 97784a8 into main Nov 12, 2026
2 checks passed
@morisil
morisil deleted the issue-235-harden-turn branch November 12, 2026 19:53
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.

Harden the turn of execute against failing waiters and double resumption, drop vacuous tests

2 participants