Skip to content

Every async terminal that was missing one takes a CancellationToken - #110

Merged
electricessence merged 24 commits into
masterfrom
feat/token-terminals
Nov 10, 2026
Merged

electricessence merged 24 commits into
masterfrom
feat/token-terminals

Conversation

@electricessence

@electricessence electricessence commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

The command's own Async terminals, IterateReader*Async, and the Channel and Dataflow overloads on an IExecuteReader ignored a token the caller had in hand; only the command's UseCancellationToken token applied. They now take CancellationToken cancellationToken = default as the last parameter. The token is used together with the command's own: either one cancels. UseCancellationToken is unchanged. The parameter is optional on purpose, so the CA2016 analyzer flags a caller who has a token and does not pass it.

How the tokens combine

  • No token on either side: the call sees a token that cannot be canceled, and allocates nothing more than before.
  • One token (or the same token on both): it is used as it is, no allocation.
  • Two different live tokens: they are linked, and the linked source is disposed when the call ends, however it ends.
  • The one token governs the whole call: the check before anything starts, opening the connection, looking up stored-procedure names, executing, the reads, and the wait for room in a channel.

What changed

Core (15 members, plus 4 new overloads):

  • ExecuteNonQueryAsync, ExecuteScalarAsync (4 forms), ExecuteReturnAsync (2 forms), ExecuteReaderAsync (5 forms).
  • IterateReaderAsync and IterateReaderWhileAsync (3 members: one IterateReaderAsync, two IterateReaderWhileAsync).
  • New: ExecuteReaderAsync(handler, cancellationToken) for the four handler shapes, because with the token last, ExecuteReaderAsync(handler, token) would not compile. ExecuteReaderAsync(handler, default) now binds to it; default is an empty token and the default behavior, so the call does the same.

Channel (20): ToChannel and ToChannelAsync on an IExecuteReader / IExecuteReaderAsync, both the ValueTask<long> forms and the ChannelReader-returning forms.

Dataflow (10): AsSourceBlockAsync and ToTargetBlockAsync on an IExecuteReader.

Where an optional parameter comes before the token (behavior, options, arrayPool, map), pass the token by name (cancellationToken: token) or pass the optional ones too. cmd.AsSourceBlockAsync(token) does not bind, as with the IDbCommand overloads.

Same signature, two meanings

ExpressiveCommandBase.ExecuteReaderAsync(state, transform, behavior, cancellationToken) combines the token with the command's. The member of the same shape on the IExecuteReader interface keeps its contract: through the interface the token replaces the command's own, because the caller has already combined them. The interface members that have no token still use the command's own token. A test pins both.

Compatibility

  • Every changed member has a new signature, so code compiled against rc.3 needs a recompile. Source stays compatible except for converting one of these terminals to a delegate by method group (below), as in earlier 11.0 pre-releases. The Unshipped API file records each old line as removed and the new one as added.
  • Converting one of these terminals to a delegate by method group (for example Func<ChannelWriter<object[]>, bool, ValueTask<long>> f = cmd.ToChannel) no longer compiles, because of the optional parameter. Use a lambda. This is a source break for that rare pattern. Four places in the tests did it and now use a lambda.
  • A literal default as the last argument binds differently where the new token overloads sit beside an ArrayPool overload. ToChannelAsync(cmd, writer, true, default) used to bind the nullable-ArrayPool overload and now binds the token one: the same call. ToChannel(cmd, writer, false, default) used to bind the non-null ArrayPool overload and threw ArgumentNullException; it now binds the token overload and runs. A test pins both.
  • A null command on the ValueTask<long> Channel overloads (ToChannel, ToChannelAsync, plain and mapped) now throws ArgumentNullException at the call, instead of returning a faulted task. A null target is still reported through the returned task.

Allocation

Passing a token must not cost an allocation. A test per family (Core terminals, IterateReader*Async, Channel) measures the bytes one call allocates on the calling thread, for a call with no token, one call token, one command token, and the same token on both, and asserts each is no more than the command token alone always allocated (slack 16 bytes). The mapped Channel overloads and Dataflow hop threads (a pipeline of their own, Task.Yield), which the per-thread counter cannot see, so they are not measured.

Tests

  • New tests cover each family: a token canceled before the call, a token canceled while a step waits, the command token with a live call token, both live (the step sees a linked token that is neither, and it is disposed afterwards), and no token. They also cover the wait for room in a bounded channel, the interface route, and the overload-resolution cases, so a later change breaks the build instead of a user.
  • A ChannelReader-returning overload is tested with a token canceled while reading, which completes the channel as canceled. A token that is already canceled before the read starts leaves such a channel open today (it is reachable with UseCancellationToken too); that is not changed here.
  • Existing tests: four method groups became lambdas, and the xUnit1051 warnings the new optional parameter caused are answered with TestContext.Current.CancellationToken, or with a scoped pragma where the test is about which token a call is given.

Checks

  • Release and Debug: build with 0 warnings and 0 errors, with code style enforced. The Core test project passes in both (9,455 tests). Checked on the tree merged with master up to Old APIs with a direct 11.0 replacement are marked [Obsolete], each naming its replacement #107. The new tests are in TokenTerminalTests (200 cases).
  • The documentation samples pass (96 checks). Style and analyzer checks at info severity: 0 findings in every source project. DocFX: 0 warnings.
  • The scans for compiler, code-style and Roslynator findings report nothing in the library files changed here, and no CA2016 anywhere in the repository; the only finding in the changed test files was one unnecessary !, which is fixed.
  • The allocation test for the channel forms failed once in an earlier full run; it has not reproduced in 30 isolated runs or in this check. Its failure message now lists the bytes every token variant measured and the slack.
  • Master's Dispose with ConfigureAwait(false) in the procedure-name queries; pin Pkcs in the benchmarks #108 is merged in. The gate on the head of this branch passes: 0 warnings in Release and in Debug, 9,455 tests passed in both, all 96 sample checks pass, 0 style and analyzer findings in every project, and DocFX 0.
  • The last four commits only reformat the lines this PR adds: one parameter per line, => on its own line, doc comments wrapped at natural breaks. The style analyzer (IDE0011) then asked for braces on multi-line if/else/foreach bodies, in IExecuteReader.cs, ExecuteReaderEdgeTests.cs and ExecuteScalarNullTests.cs; each brace pair encloses the single statement it already governed. Every changed file was compared with its previous version: the code, with whitespace removed, and the comment text are unchanged apart from those braces.

UsingAsync has no token: it creates the connection without opening it and its action receives no token, so a token there could only stop a call that is already canceled. A parameter that does almost nothing would be misleading.

If the AddParam-cost branch has not merged when this does, a later merge may conflict around the parameter-adding code in ExpressiveCommandBase.cs; this change touches the terminals and the code next to ExecuteCoreAsync.

🤖 Generated with Claude Code

electricessence and others added 24 commits November 9, 2026 15:41
…th the command's and releases the linked source

Internal and unused until the terminals take a token.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
ExecuteNonQueryAsync, ExecuteScalarAsync, ExecuteReturnAsync, ExecuteReaderAsync and IterateReader*Async take a CancellationToken as their last parameter. It is used together with the command's own token; either cancels. Code compiled against rc.3 needs a recompile; source stays compatible.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… allocated per call

The core still guards the writer, with its own parameter name, as before.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
A method group converted to a delegate (four places) becomes a lambda, as the optional token parameter makes the conversion impossible. The xUnit1051 warnings are answered with TestContext.Current.CancellationToken, or with a scoped pragma where the test is about which token a call is given.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…; say so to the analyzer

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…asured twice

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…el overloads on the small command, not the big fake reader

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…d throw on the Channel ValueTask overloads is documented and tested, and one comment is indented

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… measured and the slack

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, => on its own line, doc comments wrapped at natural breaks

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…E0011 asks

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@electricessence
electricessence marked this pull request as ready for review November 10, 2026 16:26
@electricessence
electricessence merged commit 5990731 into master Nov 10, 2026
2 checks passed
@electricessence
electricessence deleted the feat/token-terminals branch November 10, 2026 16:47
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.

1 participant