Stop recording churning metrics in the C++ docs

Remove the exact coverage totals and the offset-5 branch-coverage
explanation: both change whenever fast.cpp or the sweep is adjusted.
The coverage script already reports the current totals and enforces the
100% gate.

Replace the benchmark table's absolute nanoseconds with the stable
shape, and point readers at cr_bench for current numbers.  The recorded
crossed-truncated-reverse figure was already stale after the fast.cpp
change.
This commit is contained in:
andrew committed 2026-11-18 14:17:25 -05:00
1 parent e351a0cf8d
commit 023ed53579
2 files changed
+18 -26

No files matched your search

+18 -24
View File
@@ -117,8 +117,8 @@ It runs in about a second and is also the coverage driver. It is exhaustive
only within those bounds; the class is not all readable inputs, and the
guarantee is that every instance in this family agrees. In
particular, branch coverage cannot exercise a predicate operand that the
implementation no longer contains: the coverage result below describes the code
as written, it is not a proof of equivalence with `literal.cpp`.
implementation no longer contains: the coverage gate describes the code as
written, it is not a proof of equivalence with `literal.cpp`.
## Coverage
@@ -129,15 +129,9 @@ as written, it is not a proof of equivalence with `literal.cpp`.
The script configures a Clang source-based-coverage build, runs
`sweep_test`, and fails unless `src/fast.cpp` has 100% line and branch
coverage. `sweep_test` alone covers every region, function, line, and
branch side of the summarised implementation:
```text
src/fast.cpp 553 regions (0 missed) 119 functions (0 missed) 668 lines (0 missed) 362 branches (0 missed)
```
That is 100.00% line, function, region, and branch coverage. Offset 5 is part of
the sweep specifically to exercise the last three short-circuit branch sides,
which the previous `[-3, 4]` window missed.
branch side of the summarised implementation. The region, line, and branch
totals are not recorded here: they change with the implementation, and the
coverage run reports the current ones.
Because equivalence is only promised on readable inputs, `src/fast.cpp` deletes
both unreachable control-flow branches and predicate operands that an enclosing
@@ -196,20 +190,20 @@ constant-time instead of attempting a 2 GiB allocation.
./cpp/build/cr_bench
```
Representative results (Clang 21, default Release build: `-O3 -DNDEBUG`; medians
of nine runs pinned to one core; relative to the literal translation, lower is
better for `fast`).
CPU frequency scaling makes the absolute numbers noisy, but the shape is stable:
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 | literal | fast | fast/literal |
| --- | ---: | ---: | ---: |
| small complete (8 keys) | 41.6 ns | 16.2 ns | 0.39x |
| small truncated forward | 16.9 ns | 22.9 ns | 1.35x |
| crossed truncated forward | 56.0 ns | 46.6 ns | 0.83x |
| crossed truncated reverse | 130.1 ns | 82.7 ns | 0.64x |
| long complete forward (512 keys) | 2189 ns | 32.6 ns | 0.01x |
| long truncated forward | 15.0 ns | 19.6 ns | 1.31x |
| long truncated reverse | 9.5 ns | 12.8 ns | 1.35x |
| 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