Skip to content

Source: a cancel that cuts a reader-level read short throws; the throwOnCancellation flag is removed - #159

Merged
electricessence merged 8 commits into
masterfrom
feat/a11-cancellation-throws
Nov 16, 2026
Merged

electricessence merged 8 commits into
masterfrom
feat/a11-cancellation-throws

Conversation

@electricessence

@electricessence electricessence commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

What this changes

A cancelled ForEach, IterateWhile, Select or SelectAsync on a reader used to end quietly by default and return a partial result that looked complete: the caller got 10 or 11 rows of 100 and no exception. Now a cancellation that cuts a read short throws OperationCanceledException, and a read that completed returns its complete result.

The owner's rule: "we pass a cancellation down into the deepest depths and we let it do the cancellation for us ... at the top of the loop. Before you try to read ... throw if canceled ... You don't do something while things are canceled ... But if it completed, then it's like, oh, well, that's fine."

The rule as built.

  • Async: the token goes straight to ReadAsync and NextResultAsync, and the provider does the cancelling. A cancel during a slow read takes effect without waiting for the server (a test with a stalled ReadAsync shows it).
  • Sync: ThrowIfCancellationRequested at the top of the loop, before each Read() and before each NextResult() of the read through. A plain-reader stream checks before the read, and before skipped rows.
  • A Read or NextResult that returned false means the read is done: nothing after that throws for the token. There is no extra read after a cancel.
  • A cancel that lands while the last row is being handled throws at the next top-of-loop check; a cancel noticed after the loop has ended never throws.

The flag goes. Six shipped members are removed, and the no-flag overloads take over the throwing body, so a caller who passed true or left the flag out keeps working. Only a caller who passed false explicitly (asking for the quiet end) breaks.

  • ForEach(reader, handler, bool throwOnCancellation, token), IterateWhile(reader, predicate, bool throwOnCancellation, token), and the two SelectAsync overloads that took the flag.
  • The flag on the two Select forms: Select(reader, transform, token) (token still required, so Select(reader, transform) stays unambiguous) and its token-first twin.
  • Why each one goes: the flag's false default returned a silent partial result; once cancellation that cuts a read short throws, the flag would be a lie.

Every path follows the rule: the reader loops, ForEachAsync and the IterateWhileAsync forms (with and without useReadAsync), the command-level IterateReaderAsync/IterateReaderWhileAsync over a plain reader, and the plain-IDataReader fallback of the mapped stream (which also fixes the analyzer finding CA2016). Behaviour changes to know about: a cancel that cuts the read short now throws where a partial result used to come back as if complete (the obsolete reader ToList, ToListAsync(useReadAsync: false) and the ToChannel reader forms), and ForEachAsync and IterateWhileAsync now throw for a cancel during the last row's handler. The migration notes list each one.

Not changed (known limitation). AsAsyncEnumerable and its cores still end quietly on a cancel. The migration notes say so.

  • Public API: 6 removed lines (the shipped members above) and 2 added (Select without the flag, and its token-first twin), nothing else.
  • Tests: the old "quiet end" tests are rewritten and new ones added: cancel mid-read throws (read counts show no lookahead), cancel on the last row's handler throws, a cancel arriving with the ending read does not, a cancel before the call on an empty reader, the no-token path, nine async forms, a stalled-read test, and the binding of every call shape on C# 7.3 to 13. On master's source the new tests fail with "no exception was thrown".
  • Docs and samples: a paragraph and a compiled sample in foundation.md, new sample checks, and the migration notes.

Checks

  • Release build of the whole solution with 0 warnings; the public-API analyzer reports nothing.
  • The full Core tests pass on net10.0 and net11.0; the legacy-compiler tests pass on net472, net8.0, net10.0 and net11.0; the samples program prints "All 134 sample checks passed."
  • The full test gate and a Visual Studio MSBuild of the solution are green; leak scan clean.

🤖 Generated with Claude Code

electricessence and others added 3 commits November 16, 2026 07:11
…ancellation and the one-more-row read are removed

A canceled read on ForEach, IterateWhile, Select and SelectAsync ended quietly by default: the caller got a partial result that looked complete, after one more row was read and handled. Now a cancel that cuts the read short throws OperationCanceledException. A cancel that finds the read already finished (the read that ends the result returns no row) returns the complete result: nobody is made to throw for work that is done. The token is checked before each read; when it was canceled, one read is made to learn whether a row was still to come, and that row is not handled. A token that cannot be canceled keeps the plain loop.

The six overloads that carried the bool throwOnCancellation parameter are removed: the flag's false default returned a silent partial result, and once a cancel that cuts a read short throws, the flag would be a lie. The kept overloads take over the loops, and the token-first Select keeps its shape without the flag until it is removed with the other token-first forms. The command-level callers that passed true are updated for the signature change only. A stream of a mapped query over a plain IDataReader now forwards its token, so a cancel between rows throws there too.

Tests pin the behavior (they failed first), the overload binding is read from the IL, and the docs, a compiled sample and the migration lines say what to call instead.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ancel, one more read decides

ForEachAsync (useReadAsync), IterateWhileAsync(DbDataReader, ...) and IterateWhileAsync(IDataReader, ValueTask<bool>, ...) read with ReadAsync(token), which throws on a canceled token before a provider can say there are no more rows. So a cancel that arrived while the last row was handled threw, although the result was complete. They now read through one helper: a token canceled before the read makes that one read without it. No more rows returns the complete result; another row throws OperationCanceledException (that row is not handled). No signature changes.

Tests cover each of the six loop forms (cancel mid-read throws, cancel during the last row or as the ending read is made returns all rows) and IterateReaderAsync and IterateReaderWhileAsync over a plain reader (a small fake that implements IExecuteReaderAsync). One existing assertion changed: a call with an already canceled token now makes the one lookahead read before it throws (Reads is 1, not 0).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The useReadAsync:false branches of ForEachAsync and IterateWhileAsync, and IterateWhileAsyncInternal (used for a plain IDataReader), still used the old pattern: an extra row was handled after a cancel before the throw, and a canceled token threw up front. They now read through a synchronous twin of the lookahead helper: a token canceled before the read still makes the read; no more rows returns the complete result, another row throws OperationCanceledException and is not handled. Exception types and signatures are unchanged.

The two cancel theories now also run these three forms (nine async loop forms in all).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@electricessence
electricessence marked this pull request as ready for review November 16, 2026 16:53
electricessence and others added 5 commits November 16, 2026 10:07
Keeps both sides of Source/Core/PublicAPI.Unshipped.txt.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… let ReadAsync cancel the rest, no lookahead

The earlier rule made one more read after a cancel to learn whether the result was complete. The rule is now simpler: the token is passed down and cancels at the top of the loop, before the read. Async loops hand the token straight to ReadAsync (the provider cancels the read, also a slow one); sync loops call ThrowIfCancellationRequested before each Read() and before each NextResult() of the read-through. A read that returned no row means the read is done, and nothing after that throws for the token. There is no extra read after a cancel and no extra row handled; a cancel while the last row is handled throws at the next check.

Every loop follows it: ForEach, IterateWhile, Select, SelectAsync, ForEachAsync, every IterateWhileAsync form (with and without ReadAsync, DbDataReader and plain IDataReader) and the stream of a mapped query over a plain reader (the token check moved before the read, and the read-through checks it before each NextResult). The lookahead helper is gone; the async loops over a DbDataReader are the original ReadAsync(token) lines again.

Tests flip every case of a cancel during the last row to expect OperationCanceledException, keep the cases where the cancel arrives with the ending read (no throw), fix the Read counts, and add a cancel during a slow ReadAsync that takes effect without waiting for the server.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The ReadAsync loop conditions in ForEachAsync and IterateWhileAsync were over 80 columns. Each operand is on its own line; two loops that became multi-line got braces (IDE0011). No change of behaviour: the token stream of the file is unchanged apart from whitespace and those braces.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…with await using

The compiled sample shown in foundation.md now uses await using for the SqliteCommand and the SqliteDataReader, as the other async samples do. The sync region is unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@electricessence
electricessence merged commit 9fe6d2e into master Nov 16, 2026
7 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.

1 participant