Skip to content

Docs: the AsyncReads() how-to, with the measured reasons and four figures - #166

Merged
electricessence merged 5 commits into
masterfrom
docs/howto-asyncreads
Nov 16, 2026
Merged

electricessence merged 5 commits into
masterfrom
docs/howto-asyncreads

Conversation

@electricessence

@electricessence electricessence commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

What this changes

Adds the page that explains AsyncReads(): why it exists, what it does, what it costs and when to use it. Until now only the release notes mentioned it. Docs and samples only: no Source/, tests or public API change.

The page (docsite/articles/async-reads.md) states the default plainly (rows are read with a synchronous read, even on an async call, and AsyncReads() opts a single call into ReadAsync), shows the two side by side with equal-height code regions, and gives the reasons with their numbers:

  • the CPU cost of the opt-in, the extra memory for Map(Func) and none for Map<T>(), and the link-time case, each from a measured run and cited by run label, scenario, provider and "one run";
  • a hazard, labelled with its exact setup: on a synthetic reader with a wait every 100 rows and 8 busy thread-pool items (one run), the opt-in was far slower, which points the opposite way from "use it on a starved pool". The page does not generalise past that run;
  • what was not measured (the thread-pool benefit on a real link) is said to be unmeasured, and an inference is worded as one;
  • one sentence, with the test that pins it, that a plain IDataReader checks the token on every row under an async terminal.

Four figures (flow, cost, large value, link time) are standalone SVGs that follow the OS colour scheme like the architecture figure; each was checked in light and dark, with bars to scale.

Samples. docsite/samples/AsyncReads.cs holds six compiled regions, run by the samples program ("All 140 sample checks passed.", 134 on master, 6 new, none removed). All examples are async with a real token, static where nothing is captured, one call per line, => on the next line, and within 80 columns. toc.yml and one sentence in mapping.md link the page.

Nine files in all: the page, four SVGs, the sample, toc.yml, mapping.md and Program.cs.

Checks

  • The Samples project builds with 0 warnings and 0 errors; the samples program runs; samples style and analyzers show 0 findings.
  • DocFX builds with 0 warnings and 0 errors, and the built page shows all six code regions, the four figures with alt text and the links.
  • The quick check passes; leak scan clean.

🤖 Generated with Claude Code

electricessence and others added 5 commits November 16, 2026 10:54
…se it, with the measured costs)

A new guide page, "Row reads: sync by default, AsyncReads() to opt in":
the default stated plainly, where a thread waits (figure), the measured
reasons for the sync default (CPU, memory, wall time on a real link),
and a dedicated AsyncReads() section: what it does, when to use it, what
it costs, the busy-pool hazard and the large-value warning for Map(Func).
Every number is labeled with its run and "one run"; the thread-pool
benefit, the busy pool on a real link and Map(Func) on a 100 MB value are
marked UNMEASURED.

Four SVGs (light and dark), a compiled side-by-side sample
(AsyncReads.cs) with new sample checks, one sentence and link in the
mapping article, and one line in the table of contents. Docs only: no
Source, Tests or PublicAPI change.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…oll sideways on a phone

Each of the four SVGs now paints a solid background card (the same
--bg/--frame variables as the performance charts), so it stays readable
when the site theme and the OS color scheme differ. Data bars are solid
fills in the family colors with rounded ends and no outline. In the
article each figure sits in an overflow-x container with a 600 px
minimum width, so text never drops below 13 px at phone width. Docs
only.

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 16, 2026 21:37
@electricessence
electricessence merged commit 428abc1 into master Nov 16, 2026
7 checks passed
@electricessence
electricessence deleted the docs/howto-asyncreads branch November 16, 2026 21:38
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