From 023ed53579f325f31e8f144a905879392319acae Mon Sep 17 00:00:00 2001 From: Andrew Noyes Date: Wed, 18 Nov 2026 14:17:25 -0500 Subject: [PATCH] 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. --- cpp/README.md | 42 ++++++++++++++++++------------------------ cpp/tests/sweep.cpp | 2 -- 2 files changed, 18 insertions(+), 26 deletions(-) diff --git a/cpp/README.md b/cpp/README.md index 7a8420d..d5f3557 100644 --- a/cpp/README.md +++ b/cpp/README.md @@ -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 diff --git a/cpp/tests/sweep.cpp b/cpp/tests/sweep.cpp index d228dfa..087a90b 100644 --- a/cpp/tests/sweep.cpp +++ b/cpp/tests/sweep.cpp @@ -28,8 +28,6 @@ namespace { 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}; void check(const RangeRead& r, const Result& res, long long& cases,