Skip to content

Commit 428abc1

Browse files
Docs: the AsyncReads() how-to, with the measured reasons and four figures (#166)
* Docs: the AsyncReads() how-to (why it exists, what it does, when to use 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> * Docs: the AsyncReads() figures draw their own background card and scroll 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> * Docs: the AsyncReads() page writes microseconds as µs Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
1 parent 9fe6d2e commit 428abc1

9 files changed

Lines changed: 701 additions & 0 deletions

File tree

‎docsite/articles/async-reads.md‎

Lines changed: 154 additions & 0 deletions
Large diffs are not rendered by default.

‎docsite/articles/mapping.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -267,6 +267,8 @@ Every terminal has an `Async` twin that takes a `CancellationToken`:
267267

268268
[!code-csharp[](../samples/Mapping.cs#map_dictionary_async)]
269269

270+
An async terminal executes and opens asynchronously but reads the rows with `Read()`; [`AsyncReads()`](async-reads.md) opts one call in to `ReadAsync`.
271+
270272
## Mapping a reader or a command you already have
271273

272274
`Map<T>()` also works on a plain `IDataReader` and on a plain `IDbCommand`. `reader.Map<T>()` returns a `MappedReader<T>` and `command.Map<T>()` returns a `MappedCommand<T>`. Both have the same overloads as the expressive command's `Map` (no argument, a `RowMap<T>`, pairs, a selector) and the same terminals, synchronous and asynchronous, including `Skip`, `Take` and `Read`. The rules for mapping `T` are the ones above.

‎docsite/articles/toc.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
- href: foundation.md
44
- href: expressive-commands.md
55
- href: mapping.md
6+
- href: async-reads.md
67
- href: channels-and-dataflow.md
78
- href: performance.md
89
items:

‎docsite/images/asyncreads-cost.svg‎

Lines changed: 109 additions & 0 deletions
Loading

‎docsite/images/asyncreads-flow.svg‎

Lines changed: 99 additions & 0 deletions
Loading
Lines changed: 78 additions & 0 deletions
Loading

0 commit comments

Comments
 (0)