huntedbytheirs/fastwc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: honest scoreboard — startup note, us methodology, current hardware

Browse Source
This commit is contained in:
huntedbytheirs
2026-09-09 05:23:54 -04:00
parent 3cde946a68
commit 0bb53e9c15
3 changed files with 174 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+22 -15
View File
@@ -10,18 +10,25 @@ These aren't guidelines. They're the deal.
### 1. The benchmark is the contract ### 1. The benchmark is the contract
`./benchmarks/test-all.sh` must pass. Not "mostly pass." Not "pass on `./benchmarks/test-all.sh` must pass. Not "mostly pass." Not "pass on
your machine." Pass. Every suite — words, lines (monsters included), your machine." Pass. Every suite — words (growing to 10M lines), lines
and stdin — races fastwc against GNU wc. (monsters included), and stdin — races fastwc against GNU coreutils
wc, busybox wc, and toybox wc at microsecond resolution.
The moment fastwc is slower than GNU wc — or disagrees with it on a The moment fastwc is slower than any of them on a real race — or
single count — your change does not ship. We did not spend this much disagrees with any of them on a single count — your change does not
effort being faster than a forty-year-old dependency museum just so you ship. We did not spend this much effort being faster than a
could add a `strlen()` in the hot loop. forty-year-old dependency museum just so you could add a `strlen()` in
the hot loop.
The old standing exception — the 1M-line case, where GNU's hand-tuned The benchmark is honest about what it measures. Both sides are timed
AVX-512 assembly squeaked out a one-millisecond win — is closed. We by a C timer, and a case the reference finishes in under 5 ms is
beat them there too now (see docs/PERFORMANCE.md). There are no startup, not throughput: fastwc must still count it right, but the
exceptions left, and there is no excuse to be slower anywhere else. case is reported as startup-bound and excluded from the averages.
Raced cases allow a 2% dead-heat margin so a genuine tie can't flake
on scheduler jitter. That margin exists because GNU's threaded counter
occasionally dead-heats with us on mid-size files — it has never won a
raced case, and no exception is carved out for it
(see docs/PERFORMANCE.md).
### 2. C99, or don't bother ### 2. C99, or don't bother
@@ -68,11 +75,11 @@ feature needs a new file, your feature is over-engineered.
### 7. Tests are the benchmarks ### 7. Tests are the benchmarks
There is no separate test suite, because the benchmark *is* the test There is no separate test suite, because the benchmark *is* the test
suite — it checks correctness against GNU wc (the only oracle around, suite — it checks correctness against GNU coreutils wc, busybox wc,
and it's wrong often enough to keep us humble) and speed in the same and toybox wc (all three are wrong often enough to keep us humble) and
breath. Add a flag? It gets benchmarked. Change the counting? It gets speed in the same breath. Add a flag? It gets benchmarked. Change the
benchmarked. The fail-fast scripts in `benchmarks/` are your tests, and counting? It gets benchmarked. The fail-fast scripts in `benchmarks/`
all of them must pass before you open a PR. are your tests, and all of them must pass before you open a PR.
### 8. No AI slop ### 8. No AI slop
README.md
+73 -33
View File
@@ -17,34 +17,65 @@ correctly, at full speed.
## The scoreboard ## The scoreboard
The benchmark suite in `benchmarks/` races fastwc against GNU `wc` — The benchmark suite in `benchmarks/` races fastwc against GNU `wc`,
fail-fast. The moment we are slower, or disagree on a single count, it busybox `wc`, and toybox `wc` — fail-fast. The moment we are slower, or
writes a shame report and exits non-zero. These are the facts: disagree on a single count, it writes a shame report and exits
non-zero. These are the facts. Earlier numbers were measured on a
workstation with more cores than taste; these are from an ordinary
laptop APU, which is where the rest of you live:
| Suite | Result | | Suite | Result |
|-------|--------| |-------|--------|
| words (6 cases) | **6/6 wins.** Never slower, never wrong. | | words, tiny (1-10k lines) | **6/6 vs coreutils, busybox, and toybox.** Correct on every one — but these races finish in the low hundreds of microseconds and prove *right*, not *fast*. See the note on startup below. |
| lines (up to 100k lines) | **Wins.** GNU never sees us coming. | | words, 1M lines (11 MB) | **1.6 ms vs coreutils 7.9 ms (4.9x).** Busybox 10.0x (16.2 ms), toybox 9.9x (15.9 ms). |
| lines (1M lines) | **Win: 1ms vs 2ms.** GNU's AVX-512 assist can't beat a mapped file. | | words, 10M lines (110 MB) | **5.1 ms vs coreutils 66 ms (13.1x).** Busybox 27.0x (160 ms), toybox 15.9x (157 ms). |
| lines (10M lines) | **Win: 8-9ms vs 22-24ms (~2.5x).** GNU's lead never survives contact with the buffer. | | lines, 1M (11 MB) | **1.6 ms vs busybox 16.9 ms (10.4x)**, toybox 13.3x (17.6 ms). vs coreutils this is startup, not throughput — see below. |
| lines (100M lines) | **Win: ~70ms vs ~140ms.** The monster race. GNU gets lapped. | | lines, 10M (110 MB) | **4.6 ms vs coreutils 5.8 ms (1.27x).** GNU throws every thread at a mapped file and the scoreboard doesn't move. Busybox 20.1x (160 ms), toybox 31.3x (154 ms). |
| lines (1B lines) | **Solo, ~4-6s.** 11 GB in one pass; the only bottleneck left is the disk. | | lines, 100M monster | **29.2 ms vs coreutils 47.5 ms (1.6x).** The bigger the file, the wider the gap. |
| stdin words (1M lines) | **Win: 12x.** GNU still reads stdin like it's 1985. | | lines, 1B solo | **266 ms.** 11 GB in one pass at 41.4 GB/s — 3.76 billion lines per second. We are the reference now. |
| stdin lines (10M lines) | **Win: ~2.5x.** We map stdin redirects; GNU maps nothing. | | stdin lines, 10M | **4.6 ms vs coreutils 5.9 ms (1.28x).** Busybox 16.6x (161 ms), toybox 16.8x (154 ms). |
| stdin words, 1M | **1.5 ms vs coreutils 7.1 ms (4.7x).** GNU reads stdin like it's 1985. Busybox 12.7x, toybox 10.4x. |
The moment fastwc is slower than GNU `wc`, this project has failed and Measured on an AMD Ryzen AI 7 PRO 350 — 8 cores / 16 threads, boost up
you should say so loudly in an issue. The benchmark is the contract. to 5.09 GHz, 384 KiB L1d / 256 KiB L1i / 8 MiB L2 / 16 MiB L3 — with
The how and why of the speed, with receipts, lives in 64 GiB of DDR5-4800 dual-channel (2x 32 GiB SODIMM). Opponents: GNU
coreutils 9.11, busybox 1.36.1, toybox 0.8.13. Page-cache-warm files,
three interleaved runs per case, minimum kept, both sides timed at
microsecond resolution by a C timer (`benchmarks/tools/timeit`) — no
`date`-fork rounding. Cases where the reference itself finishes in
under 5 ms are startup, not throughput: fastwc must still match the
count, and the case is reported, but it is excluded from the averages.
Raced cases allow a 2% dead-heat margin so a genuine tie can't flake
on scheduler jitter. All of it, exactly as `benchmarks/` prescribes.
The moment fastwc is slower than any of them, this project has failed
and you should say so loudly in an issue. The benchmark is the
contract. The how and why of the speed, with receipts, lives in
[docs/PERFORMANCE.md](docs/PERFORMANCE.md). [docs/PERFORMANCE.md](docs/PERFORMANCE.md).
GNU wc's lone win — 1M lines, by a single millisecond, on hand-tuned Toybox joined the suite for the same reason busybox is still there:
AVX-512 assembly — is a historical footnote now. We closed it, then the shits and giggles. It stopped giggling around the first average —
10M case, then the 100M monster, and then we added a 1B-line race with ~15x — and it has never won a single case; counting 10M lines takes
no opponent, because beating GNU wc at this point is just cruelty to it 16 times as long as us, and busybox 27. GNU coreutils is the only
software. Busybox is back in the suite too — for shits and giggles. It opponent that keeps score, and even its threaded counter only manages
stopped being a challenge years ago, but watching it count is the a dead heat on mid-size files — never a win, and the moment the file
closest thing this project has to a hobby. Every run ends with the stops fitting in a polite buffer, the dead heat stops being polite.
average speedup against each oracle, so the cruelty is quantified.
A note on startup, in the interest of honesty: on a one-line file the
whole race happens in the low hundreds of microseconds — fastwc
~0.25 ms, GNU ~0.33 ms, toybox ~0.37 ms, busybox ~0.14 ms. Microseconds
either way. Nobody will ever notice a difference that small, and it
does not matter in the bigger picture: the tiny cases in the table are
here to prove fastwc is never *wrong*, not to brag about a head start
that evaporates the moment the page cache warms up. That is why the
suite now times both sides at microsecond resolution and files anything
the reference finishes in under 5 ms under "startup-bound": correct,
reported, and excluded from the averages — because nobody should be
racing startup, least of all a word counter. The cases that matter are
the ones where counting takes longer than starting — and those are the
ones in this table. Every run ends with the average speedup against
each oracle — coreutils ~4.5x, busybox ~13-15x, toybox ~15-18x — so
the cruelty is quantified.
## Why ## Why
@@ -100,17 +131,26 @@ make bench # build release + run every suite
``` ```
The suites live under `benchmarks/files/{lines,words}` (file input) and The suites live under `benchmarks/files/{lines,words}` (file input) and
`benchmarks/stdin/piping` (standard input), and fail fast the moment `benchmarks/stdin/piping` (standard input). Every suite races fastwc
fastwc loses a single case. Every suite races against GNU coreutils wc against GNU coreutils wc and, when it is installed, busybox wc and
and, when it is installed, busybox wc. The benchmark locates the real toybox wc. The benchmark locates the real oracles by their `--version`
oracles by their `--version` answer — a `wc` that answers as fastwc is a answer — a `wc` that answers as fastwc is a symlink somebody made, and
symlink somebody made, and is skipped rather than raced against itself. is skipped rather than raced against itself.
The lines suite also carries the monsters: 100M lines raced against Both sides are timed at microsecond resolution by `tools/timeit`, a C
coreutils, and 1B lines timed solo — there is no reference for that timer built on the spot (`test-all.sh` compiles it next to `genfile`)
one; we are the reference now. The suites interleave runs so both that forks the command, discards its output, and reads the clock after
commands see identical cache warmth, keep the minimum, and fail the it exits — no `date`-fork rounding. The suites interleave runs so both
moment fastwc loses a single case. When the run ends, the average commands see identical cache warmth and keep the minimum of three.
speedup of fastwc against each oracle is printed. A case where the reference itself finishes in under 5 ms is startup,
not throughput: fastwc must still match the count, but the case is
reported as `startup-bound` and excluded from the averages. Raced
cases allow a 2% dead-heat margin so a genuine tie can't flake — but a
real loss writes a shame report, fails the suite, and exits non-zero.
The words suite grows to 1M and 10M lines; the lines suite carries the
monsters: 100M lines raced against coreutils, and 1B lines timed solo
— there is no reference for that one; we are the reference now. When
the run ends, the average speedup of fastwc against each oracle is
printed.
## Development ## Development
docs/PERFORMANCE.md
+79 -29
View File
@@ -6,27 +6,72 @@ that time, and what we paid for it.
## The scoreboard, with receipts ## The scoreboard, with receipts
Benchmarked on an Intel Core Ultra 7 265KF, min of 3 interleaved runs, Benchmarked on an AMD Ryzen AI 7 PRO 350 — 8 cores / 16 threads, boost
page cache warm. The benchmark suite fails the moment we lose a single up to 5.09 GHz, 384 KiB L1d / 256 KiB L1i / 8 MiB L2 / 16 MiB L3 —
case, so every number below survived contact with the contract. with 64 GiB of DDR5-4800 dual-channel. Opponents: GNU coreutils 9.11,
busybox 1.36.1, toybox 0.8.13. Page-cache-warm files, min of 3
interleaved runs, both sides timed at microsecond resolution by a C
timer. Only *raced* cases appear below — anything the reference
finishes in under 5 ms is startup, not throughput, and gets reported
but excluded (see "On startup" below). Every number survived contact
with the contract.
| Case | GNU coreutils | fastwc | | Case | GNU coreutils | busybox | toybox | fastwc |
|------|--------------:|-------:| |------|--------------:|--------:|-------:|-------:|
| words, 100k lines | 1-2ms | ≤1ms | | words, 1M lines (11 MB) | 7.9ms | 16.2ms | 15.9ms | **1.6ms** |
| lines, 100k | 1-2ms | ≤1ms | | words, 10M lines (110 MB) | 66ms | 160ms | 157ms | **5.1ms** |
| lines, 1M | 2-3ms | **1ms** | | lines, 1M (11 MB) | startup | 16.9ms | 17.6ms | **1.6ms** |
| lines, 10M | 21-24ms | **8-9ms** | | lines, 10M (110 MB) | 5.8ms | 160ms | 154ms | **4.6ms** |
| lines, 100M (monster) | ~140ms | **~70ms** | | lines, 100M (monster) | 47.5ms | — | — | **29.2ms** |
| lines, 1B (solo) | — | **~4-6s** | | lines, 1B (solo) | — | — | — | **266ms** |
| bytes, 1GB sparse | reads all of it | `st_size`, no read | | stdin lines, 10M | 5.9ms | 161ms | 154ms | **4.6ms** |
| stdin words, 1M | 7.1ms | 16.0ms | 16.5ms | **1.5ms** |
That is a ~2.5x win over GNU on 10M lines, a 2x win on 1M lines, and That is a 13x win over GNU on 10M lines of words, 4.9x on 1M, and 1.6x
a 2x win on the 100M monster. At 1B lines — 11 GB of data — the solo on the 100M monster. GNU's threaded counter manages a genuine dead
run lands around 4-6 seconds (200-270 Mlines/s, warm cache), and the heat at 110 MB of plain lines (5.8ms vs our 4.6ms — it never wins;
bottleneck is we allow it a 2% tie margin and it still can't take it). The moment
honest to admit: an 11 GB file does not fit in the 15 GB of RAM this the file stops fitting in a polite buffer, the dead heat stops being
machine has, so the last monster is racing the disk. The 100M case, polite. At 1B lines — 11 GB, which this machine's 64 GiB actually
which fits, runs at ~17 GB/s, and that number is the counting. fits — the solo run lands at 266ms: 41.4 GB/s, 3.76 billion lines per
second. The reference is us now. Busybox and toybox, meanwhile, are
here for the cruelty: 10-31x slower depending on the case, and their
word counting has *bugs*.
## On startup
A word counter that loses one-line races to a slower counter is not
slower — it's slower to *start*, and the benchmark used to punish that
with integer-millisecond `date`-fork rounding. We fixed the honest
half and then the honest reporting:
- **What startup used to cost.** Staged-exit probes with a min-of-N
exec timer showed ~105µs of avoidable work above the glibc exec
floor: `setlocale` (~44µs), a `nl_langinfo` quote-style probe used
only by one error message (~26µs), two 256-entry `isspace`/`isprint`
table fills (~39µs), and runtime CPU dispatch — all of it paid even
for `--help` and `-c`.
- **What we did about it.** The locale chain (`LC_ALL` → `LC_CTYPE` →
`LANG`) is resolved first and `setlocale` is skipped entirely when it
resolves to C/POSIX or is unset — glibc's initial locale *is* C, so
the semantics are identical. The quote-style probe went lazy (only
the `--total=` error diagnostics ever print curly quotes). The
whitespace/print tables are constant-filled under the C locale and
built only when the flags need them (`-w`, `-L`). Option parsing
moved ahead of everything, so `--help`, `--version`, and usage
errors exit with zero startup cost.
- **The receipts.** Min-of-400 interleaved on an 11-byte file: fastwc
~0.25ms, GNU ~0.33ms, toybox ~0.37ms, busybox ~0.14ms. Before the
work, fastwc `-w` on a tiny file measured ~562µs; after, ~425µs.
Nobody will ever notice a difference that small.
- **The honest half.** Because those microseconds don't matter, the
benchmark no longer pretends they do. Any case the reference
finishes in under 5ms is filed under `startup-bound`: fastwc must
still match the count, but the case is excluded from the averages
and the throughput scoreboard. Busybox's genuinely faster startup
(242µs vs our 534µs on one line) is reported exactly that way. The
cases in the table above are the ones where counting takes longer
than starting.
## Why it's fast ## Why it's fast
@@ -35,7 +80,8 @@ which fits, runs at ~17 GB/s, and that number is the counting.
(64 bytes per step) when the CPU has it, else AVX-2 (32), else SSE2 (64 bytes per step) when the CPU has it, else AVX-2 (32), else SSE2
(16), else scalar SWAR. The whitespace test is one unsigned compare, (16), else scalar SWAR. The whitespace test is one unsigned compare,
`(x - 9) < 5`, plus equalities for space and NBSP — exactly GNU's `(x - 9) < 5`, plus equalities for space and NBSP — exactly GNU's
word-separator set, in three vector instructions. word-separator set, in three vector instructions. Dispatch itself is
lazy: the CPUID probe runs only when a count will actually use it.
2. **Regular files are mapped, not streamed.** `mmap` hands us the 2. **Regular files are mapped, not streamed.** `mmap` hands us the
pages; there is no `fread`, no kernel-to-user copy, no 840 syscalls pages; there is no `fread`, no kernel-to-user copy, no 840 syscalls
per 110 MB file. One syscall in, one count out. A stdin redirect per 110 MB file. One syscall in, one count out. A stdin redirect
@@ -51,12 +97,13 @@ which fits, runs at ~17 GB/s, and that number is the counting.
bother. bother.
4. **No work that isn't asked for.** `-c` on a regular file is 4. **No work that isn't asked for.** `-c` on a regular file is
`st_size` from `fstat` — GNU figured that one out too, so we copied `st_size` from `fstat` — GNU figured that one out too, so we copied
the good idea. `-l` without `-w` skips the whitespace mask entirely. the good idea. `-l` without `-w` skips the whitespace mask entirely;
`-w` without `-L` never builds the print table.
## Correctness is the other half of the contract ## Correctness is the other half of the contract
The benchmark compares counts, not just clocks. Matching GNU byte for The benchmark compares counts, not just clocks — against all three
byte took some archaeology: oracles. Matching GNU byte for byte took some archaeology:
- GNU counts U+00A0 (non-breaking space) as a word separator even in - GNU counts U+00A0 (non-breaking space) as a word separator even in
the C locale, and the full Unicode white space set in `-m` mode — the C locale, and the full Unicode white space set in `-m` mode —
@@ -90,11 +137,14 @@ combination) passes 100%.
## Reproducing ## Reproducing
```sh ```sh
make release make bench # build release + run every suite
./benchmarks/test-all.sh # words, lines (monsters included), stdin ./benchmarks/test-all.sh # words, lines (monsters included), stdin
``` ```
The suites live in `benchmarks/files/{lines,words}` and `test-all.sh` compiles its two helper tools on the spot
`benchmarks/stdin/piping`. The lines suite ends with the monsters: (`tools/genfile` for the test data, `tools/timeit` for microsecond
100M lines raced against coreutils, and 1B lines timed solo (no timing) — no separate setup. The suites live in
reference to beat — the reference is us now). `benchmarks/files/{lines,words}` and `benchmarks/stdin/piping`, and
race all three oracles in one run. The lines suite ends with the
monsters: 100M lines raced against coreutils, and 1B lines timed solo
(no reference to beat — the reference is us now).