Point the benchmark section at cr_bench

Remove the recorded benchmark tables.  They are measurements of a
particular machine and build, and they go stale as soon as the
implementation or harness changes.  Leave the command and a one-line
description of what it compares, so the reader can run it.
This commit is contained in:
andrew committed 2026-11-18 14:18:15 -05:00
1 parent 023ed53579
commit fad9095062
1 file changed
+7 -44
+7 -44
View File
@@ -186,54 +186,17 @@ constant-time instead of attempting a 2 GiB allocation.
## Benchmark
`cr_bench` compares the literal translation with the summarised implementation
across small and long complete, truncated, and crossed reads in both traversal
directions:
```sh
./cpp/build/cr_bench
```
Representative shape (Clang 21, default Release build: `-O3 -DNDEBUG`;
run `cr_bench` for current numbers, which vary with the machine and the
implementation; relative to the literal translation, lower is better for
`fast`).
| case | shape |
| --- | --- |
| small complete (8 keys) | much faster |
| small truncated forward | slightly slower |
| crossed truncated forward | faster |
| crossed truncated reverse | roughly twice as fast |
| long complete forward (512 keys) | much faster |
| long truncated forward | slightly slower |
| long truncated reverse | slightly slower |
The large win is on complete reads: the literal translation rescans the reported
keys many times (`residualT`, `reportedBelowBegin`, `allBelowEnd`, ...), while
the summary answers those questions in `O(log n)` or from a cached count.
Plain truncated cases are dominated by the shared decision tree, so the two
implementations are close; the literal path is slightly cheaper there because it
performs no summary setup. Crossed cases report 16 of a 33-key range, so the
summary wins there too.
Against the same implementation with owned input keys (the previous model), the
borrowed-key model changes the costs as follows (nine interleaved runs each,
median). The crossed cases are absent from this table: their benchmark inputs
were corrected to nonempty ranges after the owned-key measurements.
| case | literal (borrow vs own) | fast (borrow vs own) |
| --- | ---: | ---: |
| small complete | -64% | -17% |
| small truncated forward | -33% | -19% |
| long complete forward | -69% | -15% |
| long truncated forward | -29% | -6% |
| long truncated reverse | -16% | +16% |
The complete-read gains come from not copying the reported keys just to
normalise the result: a forward result is now the caller's span, and a reverse
result is a reversed view rather than an owned copy. The fast path also benefits
because it previously normalised complete results the same way. Truncated
reverse (`fast`) is the one small regression: it is a few nanoseconds and a few
dozen instructions, and the other paths move in the opposite direction, so it
reads as code-layout/code-generation noise rather than extra algorithmic work.
It reports timings and instruction and branch counts per case. Absolute numbers
vary with the machine, compiler, and frequency scaling, so run it for current
figures.
## Why the fast implementation is equivalent