[NetKAT] Speed up PagedStableVector indexing with power-of-two page sizes

[smolkaj]

Note

Stacked on #105 — the first two commits shown here belong to that PR. Review only the four commits starting at "Simplify PagedStableVector bookkeeping"; this PR will be rebased once #105 merges.

The win

This PR hardens and instruments the node arena after #105 right-sizes its pages:

• Compile-time enforcement that PagedStableVector page sizes are powers of two — the property that makes its operator[] (the hot path of nearly every BDD operation, via GetNodeOrDie) compile to shifts/masks and run 1.1–2.6× faster than with a non-power-of-two page size, matching a flat std::vector on sequential reads. [NetKAT] Shrink node storage pages from 64 MiB to 16 KiB #105 chooses such page sizes; this PR makes choosing anything else a compile error rather than a silent regression.
• A latent exception-safety bug fixed in push_back/emplace_back.
• Benchmark infrastructure the repo was missing: a PagedStableVector microbenchmark and large-scale (~10^5–10^6 node) packet-set benchmarks — the latter already used to validate [NetKAT] Shrink node storage pages from 64 MiB to 16 KiB #105's claims.

End-to-end, the arena-level changes are worth ~1–3% (see "How much this matters" below); the big wins here are robustness and measurement.

The story

PagedStableVector::operator[] computes index / PageSize and index % PageSize on every access. When the page size is derived from a byte budget — as it was on head, and as #105 initially did — the element count is generally not a power of two, so the compiler emits multiply-based division sequences instead of single shift/mask instructions. The transformer manager only ever escaped this by luck (64-byte nodes happen to divide byte budgets evenly).

With #105 defining both page sizes as power-of-two node counts, this PR adds static_assert(std::has_single_bit(PageSize)) to PagedStableVector itself, turning the convention into a guarantee.

The push_back/emplace_back bookkeeping is also simplified: page boundaries are detected via the last page's size rather than recomputing size() % PageSize per insertion. Besides being cheaper, this fixes a latent invariant bug: if an insertion threw after allocating a fresh page, the next insertion would allocate a second empty page, leaving a hole mid-vector that silently corrupts the index arithmetic for all subsequent elements. (Unreachable today since DecisionNode insertions don't throw, but a footgun for future element types.)

Microbenchmark proof

The power-of-two impact was measured with a temporary variant of the new paged_stable_vector_benchmark instantiating both page-size flavors in the same binary (perfectly load-matched), at L3-resident (256k elements) and DRAM-resident (4M elements) working-set sizes. CPU-time medians, 5 repetitions:

Benchmark	non-pow2 pages	pow2 pages	speedup
Sequential read, 256k elems (L3)	222.6 µs	84.7 µs	2.6×
Sequential read, 4M elems (DRAM)	3.72 ms	2.15 ms	1.7×
Random read, 256k elems (L3)	385 µs	292 µs	1.3×
Random read, 4M elems (DRAM)	37.0 ms	33.1 ms	1.1×

The committed benchmark uses the production page size (512 nodes per #105) and keeps the long-term job of guarding paged-vs-flat performance: with the small pages, paged sequential reads still match flat std::vector (2.081 ms vs 2.070 ms at 4M elements — the 8k-entry page table costs nothing measurable), and paged appends still beat flat by ~1.4× thanks to the absence of relocation copies.

How much this matters end to end

The pre-existing benchmarks compile predicates of only tens of BDD nodes — far too small to exercise the arena. This PR adds large-scale benchmarks to packet_set_benchmark: pseudo-random sets drawn from a ~1M element space over 5 hex-digit fields, whose incompressible BDDs reach ~10^5–10^6 nodes like real-world models. The arena-level changes (power-of-two indexing + cheaper appends) are worth ~1–3% end to end on these workloads — node creation is dominated by unique-table hashing (each DecisionNode hash includes its heap-allocated branch array) and flat_hash_map probing, which dwarf the few instructions saved per arena access. The big end-to-end levers are algorithmic and already tracked: operation memoization (b/382379263) and complement edges (b/382380335) — today Or is Not(And(Not(l), Not(r))) and Not copies its entire operand. These benchmarks double as the yardstick for that future work, and were already used to verify #105's "large workloads unaffected" claim (they improved ~8%).

All 17 bazel test targets pass in -c opt. The pointer-stability test is also strengthened: it now holds a reference to every element across several pages (the boundary-adjacent positions are the ones most at risk during page allocation), rather than just the first two elements of the first page.

🤖 Generated with Claude Code

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.