Repository navigation
Conversation
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
force-pushed
the
feat/kll-lazy-allocation
branch
from
October 20, 2026 19:06
de4b335 to
f1aee0c
Compare
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
A new
KLLallocated 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.max_capacity. Growing moves the retained items to the high end of the new buffer and shifts every level boundary by the growth.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).merge,clear,from_portable_stateand 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.#[cold], out-of-linemake_room, so the insert path stays small.KLL::memory_bytes()andKllSketch::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_eagercompares 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).kll::tests::memory_follows_the_items_heldandportable::kll::tests::memory_bytes_follows_the_items_held.kll_round_trip_rmpnow 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):
perf statover 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-targetswith and without--all-features,-D warnings;cargo test --all-features --locked(2,331 passed) andcargo test --locked(2,070 passed).