Skip to content

perf(kll): allocate the item buffer as items arrive - #238

Open
zzylol wants to merge 1 commit into
mainfrom
feat/kll-lazy-allocation
Open

zzylol wants to merge 1 commit into
mainfrom
feat/kll-lazy-allocation

Conversation

@zzylol

@zzylol zzylol commented Oct 19, 2026

Copy link
Copy Markdown
Contributor

A new KLL allocated its whole item buffer at construction (1,796 items, about 14 KiB, at k = 469) and a k-sized merge scratch buffer (about 3.7 KiB). Most per-series sketches in a pane store hold a handful of items, so creating them was dominated by allocating and zeroing memory they never use. In a per-sample ingestion profile, KLL creation was about a third of data-plane CPU, mostly memset and page faults.

  • Lazy item buffer. The buffer starts empty, then holds 16 items, and doubles up to the sketch's max_capacity. Growing moves the retained items to the high end of the new buffer and shifts every level boundary by the growth.
  • Results are unchanged.
    • Compaction reads only level sizes and positions relative to one another.
    • A full buffer compacts only once it has reached max_capacity, as an eagerly allocated one did. When a partial buffer fills, every level is already within capacity (L0 compacts right after the insert that overflows it).
    • So the retained items, their order, the coin tosses, quantiles, merges and serialized bytes are those of the eager buffer for the same input and seed.
  • The merge scratch buffer starts empty and grows on first use.
  • merge, clear, from_portable_state and both decoders (the ASAPv1 payload and the nested serde form) size the buffer to what they hold. A decoded sketch's buffer holds just its retained items.
  • The full-buffer path (grow, or compact once whole) moved into a #[cold], out-of-line make_room, so the insert path stays small.
  • New: KLL::memory_bytes() and KllSketch::memory_bytes(). They report the bytes a sketch holds: the struct, its item buffer, its level array, its merge scratch space, and a memoized CDF when one is held. A caller that charged a KLL a fixed size can charge what it holds. A k = 469 sketch with 10 items holds 872 bytes, against 18,864 before.

Tests:

  • kll::tests::lazy_allocation_matches_eager compares every level's retained items, in buffer order, and the coin state with a test-only copy of the eager allocation path (kll/eager_reference.rs).
    • It covers k = 8, 64, 200, 469 and 1024; inputs of 0, 1, 10, k − 1, k, k + 1, 3k, 10k and 50,000 items; and two seeds.
    • Each case then merges a second sketch and adds more items.
    • The serializers write exactly that state plus k, m and the seed, so equal state means equal bytes.
    • An extra coin toss on growth makes it fail.
  • kll::tests::memory_follows_the_items_held and portable::kll::tests::memory_bytes_follows_the_items_held.
  • kll_round_trip_rmp now compares level boundaries relative to the first retained item. The restored buffer holds just the retained items, while the source's buffer grew in doublings, so absolute positions differ. Level sizes and items are compared as before.

Benchmark (release, one pinned core, main e0f5711 vs this branch, alternating runs in one session, median of 3):

main this branch
Create 1,000,000 KLLs (k = 469), 10 updates each, held 10,000 at a time 13,710 ns/sketch 1,240 ns/sketch (11.1× faster)
Peak RSS of that run 178 MiB 10 MiB
One KLL, 50M updates, k = 469 33.69 ns/update 33.90 ns/update (+0.6%)
One KLL, 50M updates, k = 200 33.31 ns/update 33.65 ns/update (+1.0%)
  • Stream cost: an earlier 5-pair pass measured about +1.8% for the stream. perf stat over the stream run shows this branch executing 0.7% fewer instructions with the same branch, L1, LLC and dTLB misses. Per-function cycle shares are within 1.5 points of main's. So the remaining difference is in code layout, not extra work on the insert path.

Verification: cargo fmt --all -- --check; cargo clippy --workspace --all-targets with and without --all-features, -D warnings; cargo test --all-features --locked (2,331 passed) and cargo test --locked (2,070 passed).

@zzylol zzylol added the enhancement New feature or request label Oct 19, 2026
A new KLL allocated its whole item buffer (about 14 KiB at k = 469) and
a k-sized merge scratch buffer up front. Most per-series sketches hold far
fewer items than k, so creating them was dominated by allocating and
zeroing memory they never use.

- The buffer starts empty, then 16 items, and doubles up to the sketch's
  max capacity; growing moves the retained items to the high end of the
  new buffer and shifts every level boundary by the growth. Compaction
  still reads only level sizes and relative positions, and a full buffer
  compacts only once it has reached max capacity, so the retained items,
  their order and the coin tosses are those of the eager buffer.
- The merge scratch buffer starts empty.
- Merge, clear, from_portable_state and the ASAPv1 decoder size the buffer to
  what they hold.
- Kll::memory_bytes reports the bytes the sketch holds.

Tests: lazy_allocation_matches_eager compares every level's items and the
coin with a test-only copy of the eager path (k = 8 to 1024, from empty
to 50,000 items, with a merge and updates after it);
memory_follows_the_items_held.
@zzylol
zzylol force-pushed the feat/kll-lazy-allocation branch from de4b335 to f1aee0c Compare October 20, 2026 19:06
GordonYuanyc added a commit that referenced this pull request Oct 20, 2026
…223, #228, #229, #233, #238) (#242)

* feat(univmon): check_shape refuses a pyramid shape without building it

`UnivMon::check_shape(heap_size, rows, cols, layers)` accepts exactly the
shapes `UnivMon::new` builds: positive dimensions, at most UNIVMON_MAX_LAYERS
layers, at most MATRIX_MAX_ROWS rows, rows within the 128-bit hash budget and
a counter count that fits usize. `new` panics exactly when it fails, so it no
longer builds a pyramid the ASAPv1 wire refuses.

Ports #229.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(univmon): count every cardinality candidate, direct L2, documented error bounds

`estimate_cardinality` counts every heap key, including zero-weight keys and
keys whose Count Sketch estimate is not positive. `estimate_l2` reads layer 0's
Count Sketch F2 estimate in standard mode and sums the strata's F2 estimates in
terminal mode; `estimate_g_sum` keeps the paper's recurrence, and its flag is
now `count_every_key` (`true` counts every heap key). New
`top_layer_complete()`. The L2 bound and the distinct-count bound, stated
jointly with `top_layer_complete()`, are derived in docs/api/api_univmon.md,
with Monte Carlo tests.

Ports #221.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(univmon_two_tier): count every cardinality candidate and direct L2

`UnivMonTwoTier` gets the estimators `UnivMon` has: `estimate_cardinality`
counts every heap key whatever its estimate, zero-weight keys included;
`estimate_l2` reads layer 0's Count Sketch F2 estimate in standard mode and
sums the strata's in terminal mode; new `top_layer_complete()`. The API doc
states the bounds in the two-tier layout's terms, with Monte Carlo tests.

Ports #222.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(hydra): group-total query from per-cell mass

`Hydra::query_group_total(key)` returns a subpopulation's estimated total
mass: the minimum over rows of the subkey's cell `HydraCounter::total_mass()`,
a Count-Min cell's inner row sum or a KLL cell's retained weight. Count Sketch,
HyperLogLog and UnivMon counters return an error. The total is read from
existing cell state, so the wire format is unchanged. `query_key` and the new
query share one subkey hash helper.

Ports #223.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* perf(kll): allocate the item buffer as items arrive

Kll's item buffer starts empty, then holds 16 items and doubles up to
max_capacity; a full buffer compacts only at max_capacity, so retained
items, coin tosses, quantiles, merges and ASAPv1 bytes match the eagerly
allocated buffer for the same input and seed. The merge scratch buffer
starts empty; merge, from_portable_state and the ASAPv1 decoder size the
buffer to what they hold.

lazy_allocation_matches_eager compares every level and the coin with a
test-only eager copy (k = 8 to 1024, up to 50,000 items, with a merge).

Ports #238.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(kll): Kll::memory_bytes and KllDynamic::memory_bytes

Both report the bytes the sketch holds now: Kll its struct, item buffer,
level array, merge scratch space and memoized CDF; KllDynamic its struct,
item buffer and level bounds.

Ports #238.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(kmv): estimate and merge by shared reference, memory_bytes, early reject past the k-th hash

Kmv::estimate takes &self and Kmv::merge takes &Kmv. Kmv::memory_bytes
is the struct plus the hash slots the heap has allocated
(CommonHeap::allocated_slots, crate-private). A full sketch turns away a
hash at or above its largest retained one before scanning the retained
hashes for a duplicate; the retained set and every estimate are unchanged.

Ports #228.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(heap)!: TopKHeap::estimated_memory_bytes; UnivMonQ::memory_bytes

TopKHeap::estimated_memory_bytes(heap_size, key) is the bytes a heap of
that capacity holds in steady state once keys shaped like key churn
through it: the struct, entry and digest arrays, the digest index (std
HashMap layout, grown once more when tombstones force a resize of an index
over half full) and the owned key bytes. A heap holds at most this.

UnivMonQ::estimated_memory_bytes(&self) becomes memory_bytes(&self) and
counts what the instance holds: its counters, candidate tables (bucket
count from the largest capacity() seen), candidate heaps and ordered-sample
heap.

tests/heap_memory_bytes.rs checks both against a counting global
allocator: the heap estimate as an upper bound after a fill and exactly
after churn, UnivMon-Q exactly.

Ports #233 (the heap half).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(cms,cs)!: check_shape, clear and memory accounting for the matrix sketches

CountMinSketch, CountSketch and their WithHeap and WithSpaceSaving forms
gain check_shape(rows, cols), which accepts the ASAPv1 geometry,
1 <= rows <= MATRIX_MAX_ROWS and 1 <= cols <= u32::MAX, on every hashing
path. with_dimensions, new and from_storage panic on any other shape. Past
20 rows the regular path and the fast path's per-row (Rows) layout hash
row r + 20 with row r's seed; the packed layouts reuse no seed. Tests that
built such a shape to watch the encoder refuse it check check_shape
instead, Hydra's included.

clear() zeroes the counters (and empties the heap for the WithHeap types)
and returns the Nitro sampler to its start (Nitro::reset, through the new
MatrixStorage::reset_sampler), keeping shape, allocation and admission
rate.

TopKHeap::memory_bytes reports the bytes a heap holds, taking the digest
index's bucket count from the largest capacity() it has reported, which
evictions' tombstones cannot lower. The WithHeap types add memory_bytes
and estimated_memory_bytes(rows, cols, heap_size, key).
tests/heap_memory_bytes.rs checks all of them against a counting
allocator, after a fill and after 50 times heap_size evicting keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(hash)!: a seed for every seed index; matrix sketches take any row count

Seed index i hashes with seed_for_index(i) = SEED_LIST[i % 20] *
(i / 20 + 1) + i / 20 in wrapping u64 arithmetic; indexes below 20 keep
their seed. The matrix hash passes seed indexes through unreduced, so rows
past 20 on the regular path and the fast path's per-row layout hash
independently, and UnivMon-Q's occurrence priorities hash at their own seed.

check_shape on Count-Min, Count Sketch and their WithHeap and
WithSpaceSaving forms refuses only a zero dimension and a counter count past
usize; Elastic, Hydra and UnivMon build any row count. to_asapv1 and
from_asapv1 keep the MATRIX_MAX_ROWS bound.

The UnivMon-Q residual-CDF accuracy test hashes each of its 32 sketches at
its own seed index.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(cms,cs)!: memory_bytes, CountMinF64 at the root, check_shape without type parameters

CountMinSketch and CountSketch gain memory_bytes(&self): the struct plus
its rows * cols counters, exact for Vector2D storage, checked against a
counting allocator in tests/heap_memory_bytes.rs. CountMinF64 is
re-exported from sketches and the crate root.

check_shape on CountMinSketch, CountSketch, their WithHeap and
WithSpaceSaving forms is defined on the type with its default parameters,
so CountMinSketch::check_shape(3, 64) resolves without naming storage,
path or hasher. A call naming non-default type parameters no longer
compiles.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat(asapv1)!: seed_derivation is "seed_list_index_scaled"

The ASAPv1 seed_derivation string names seed_for_index. Bytes carrying
"seed_list_index_wrap" no longer decode. The golden submodule moves to the
regenerated fixtures (sketchlib-golden-bytes#3).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: zz_y <zeyingz@umd.edu>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant