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 only within those bounds; the class is not all readable inputs, and the
guarantee is that every instance in this family agrees. In guarantee is that every instance in this family agrees. In
particular, branch coverage cannot exercise a predicate operand that the particular, branch coverage cannot exercise a predicate operand that the
implementation no longer contains: the coverage result below describes the code implementation no longer contains: the coverage gate describes the code as
as written, it is not a proof of equivalence with `literal.cpp`. written, it is not a proof of equivalence with `literal.cpp`.
## Coverage ## 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 The script configures a Clang source-based-coverage build, runs
`sweep_test`, and fails unless `src/fast.cpp` has 100% line and branch `sweep_test`, and fails unless `src/fast.cpp` has 100% line and branch
coverage. `sweep_test` alone covers every region, function, line, and coverage. `sweep_test` alone covers every region, function, line, and
branch side of the summarised implementation: branch side of the summarised implementation. The region, line, and branch
totals are not recorded here: they change with the implementation, and the
```text coverage run reports the current ones.
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.
Because equivalence is only promised on readable inputs, `src/fast.cpp` deletes Because equivalence is only promised on readable inputs, `src/fast.cpp` deletes
both unreachable control-flow branches and predicate operands that an enclosing 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 ./cpp/build/cr_bench
``` ```
Representative results (Clang 21, default Release build: `-O3 -DNDEBUG`; medians Representative shape (Clang 21, default Release build: `-O3 -DNDEBUG`;
of nine runs pinned to one core; relative to the literal translation, lower is run `cr_bench` for current numbers, which vary with the machine and the
better for `fast`). implementation; relative to the literal translation, lower is better for
CPU frequency scaling makes the absolute numbers noisy, but the shape is stable: `fast`).
| case | literal | fast | fast/literal | | case | shape |
| --- | ---: | ---: | ---: | | --- | --- |
| small complete (8 keys) | 41.6 ns | 16.2 ns | 0.39x | | small complete (8 keys) | much faster |
| small truncated forward | 16.9 ns | 22.9 ns | 1.35x | | small truncated forward | slightly slower |
| crossed truncated forward | 56.0 ns | 46.6 ns | 0.83x | | crossed truncated forward | faster |
| crossed truncated reverse | 130.1 ns | 82.7 ns | 0.64x | | crossed truncated reverse | roughly twice as fast |
| long complete forward (512 keys) | 2189 ns | 32.6 ns | 0.01x | | long complete forward (512 keys) | much faster |
| long truncated forward | 15.0 ns | 19.6 ns | 1.31x | | long truncated forward | slightly slower |
| long truncated reverse | 9.5 ns | 12.8 ns | 1.35x | | long truncated reverse | slightly slower |
The large win is on complete reads: the literal translation rescans the reported The large win is on complete reads: the literal translation rescans the reported
keys many times (`residualT`, `reportedBelowBegin`, `allBelowEnd`, ...), while keys many times (`residualT`, `reportedBelowBegin`, `allBelowEnd`, ...), while
-2
View File
@@ -28,8 +28,6 @@ namespace {
using namespace cr; using namespace cr;
// Offset 5 is what lets the default sweep exercise the last three
// short-circuit branch sides in `fast.cpp` (all in crossed subtrees).
const std::int32_t kOffsets[] = {-3, -2, -1, 0, 1, 2, 3, 4, 5}; const std::int32_t kOffsets[] = {-3, -2, -1, 0, 1, 2, 3, 4, 5};
void check(const RangeRead& r, const Result& res, long long& cases, void check(const RangeRead& r, const Result& res, long long& cases,