Covers setup (build.zig.zon + zbench_build helper), the minimal
benchmark shape, the Benchmark API surface, timer control,
sub-benchmarks, comptime-parametric generation, CLI flags, JSON
output, and the optimizer pitfall around trivial loops.
Examples covering the main usage patterns:
- bench_append_u8: per-iteration heap work, demonstrates B/op tracking
via the wrapped allocator.
- bench_sha256_64: set_bytes() for throughput in MB/s.
- bench_integer_sum: shows the optimization pitfall with a comment —
trivial loop bodies need an in-loop b.keep to survive ReleaseFast.
- bench_hash_sizes: parent that delegates to sub-benchmarks via b.run,
printed as `hash_sizes/sha256_<size>`.
- memset_{16,256,4096}: comptime-parametric benchmark generation via
std.fmt.comptimePrint + a generic gen_bench factory.
Includes a stand-alone examples/bench/build.zig illustrating the
zbench_build.add_bench_step integration a downstream project would use.
- root.zig: re-exports Benchmark, Suite, Options, Format, Result,
BenchFn, parse_duration_ns; also pulls every submodule into the test
block so `zig build test` covers them.
- build_helper.zig: add_bench_step(b, opts) factory that creates the
benchmark executable (ReleaseFast by default), wires zbench and any
extra modules, attaches an addRunArtifact forwarding `--` args, and
registers a `zig build <step_name>` step.
- reporter.zig: text table writer (Go-compatible columns, mean ± stddev
when --count > 1) and ndjson writer, both driving std.Io.Writer.
- suite.zig: Suite holds registered (name, fn) entries, owns name
storage, drives run/run_cli, and routes sub-benchmark calls back
through a sub_run trampoline using current_name to compose
parent/child paths. Parses --filter / --min-time / --count /
--max-iters / --allocs / --format / --list / --help, with a small
duration parser (1s, 500ms, 100us, 250ns).
Adds the measurement core:
- CountingAllocator: a thin wrapper over std.mem.Allocator vtable that
tracks alloc/free counts and total bytes allocated, exposing a reset()
used between attempts of the adaptive loop.
- stats.summarize: min / mean / sample stddev over an array of f64,
used to aggregate --count repetitions.
- Benchmark: user-facing handle passed to each bench fn — n,
allocator (counting-wrapped), io, with snake_case methods
reset_timer / stop_timer / start_timer / set_bytes / report_allocs /
keep / run (sub-bench). Times via std.Io.Timestamp.now(io, .awake).
- runner.run_one: galloping iteration count toward --min-time, with
×100 growth cap per step and "nice-number" rounding, matching Go's
testing pkg heuristic.
Initial Zig 0.16 build script wiring the public `zbench` module, the
`zbench_build` helper module for downstream `build.zig` files, an
internal `test` step, and an `example` step that compiles and runs the
bundled benchmark suite.
