From 32af9d64626b00820155c3b4bb6832a739da554d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Milo=C5=A1=20Stojko?= Date: Tue, 10 Nov 2026 09:56:37 +0000 Subject: [PATCH 1/7] perf: kll_sketch grows its items buffer by 8x up to k A new sketch has room for min(k, 200) items instead of k, and a full buffer smaller than k grows by RESIZE_FACTOR (X8) up to k. Compaction still starts only when the buffer holds k items, and while there is one level the serialized levels are offsets into a buffer of k items, so results and serialized bytes do not change. Co-authored-by: Isaac --- kll/include/kll_sketch.hpp | 9 +- kll/include/kll_sketch_impl.hpp | 42 ++++++- kll/test/kll_sketch_test.cpp | 213 ++++++++++++++++++++++++++++++++ 3 files changed, 257 insertions(+), 7 deletions(-) diff --git a/kll/include/kll_sketch.hpp b/kll/include/kll_sketch.hpp index 274d5bec..5f840fcc 100644 --- a/kll/include/kll_sketch.hpp +++ b/kll/include/kll_sketch.hpp @@ -183,7 +183,9 @@ class kll_sketch { using quantile_return_type = typename quantiles_sorted_view::quantile_return_type; /** - * Constructor + * Constructor. + * The items buffer starts with space for min(k, DEFAULT_K) items (k items if RESIZE_FACTOR is X1), + * and grows by RESIZE_FACTOR up to k items before the first compaction. * @param k affects the size of the sketch and its estimation error * @param comparator strict weak ordering function (see C++ named requirements: Compare) * @param allocator used by this sketch to allocate memory @@ -550,6 +552,10 @@ class kll_sketch { static const uint8_t PREAMBLE_INTS_SHORT = 2; // for empty and single item static const uint8_t PREAMBLE_INTS_FULL = 5; + // growth factor of the items buffer until it holds k items + static const resize_factor RESIZE_FACTOR = resize_factor::X8; + static_assert(RESIZE_FACTOR >= resize_factor::X1, "RESIZE_FACTOR must be at least X1"); + C comparator_; A allocator_; uint16_t k_; @@ -581,6 +587,7 @@ class kll_sketch { uint8_t find_level_to_compact() const; void add_empty_top_level_to_completely_full_sketch(); + void grow_items(); void sort_level_zero(); template void merge_higher_levels(O&& other, uint64_t final_n); diff --git a/kll/include/kll_sketch_impl.hpp b/kll/include/kll_sketch_impl.hpp index e1ed85ec..ffd3af20 100644 --- a/kll/include/kll_sketch_impl.hpp +++ b/kll/include/kll_sketch_impl.hpp @@ -45,7 +45,7 @@ is_level_zero_sorted_(false), n_(0), levels_(2, 0, allocator), items_(nullptr), -items_size_(k_), +items_size_(RESIZE_FACTOR == resize_factor::X1 ? k_ : std::min(k_, kll_constants::DEFAULT_K)), min_item_(), max_item_(), sorted_view_(nullptr) @@ -54,7 +54,7 @@ sorted_view_(nullptr) throw std::invalid_argument("K must be >= " + std::to_string(kll_constants::MIN_K) + " and <= " + std::to_string(kll_constants::MAX_K) + ": " + std::to_string(k)); } - levels_[0] = levels_[1] = k; + levels_[0] = levels_[1] = items_size_; items_ = allocator_.allocate(items_size_); } @@ -199,7 +199,13 @@ void kll_sketch::update_min_max(const T& item) { template uint32_t kll_sketch::internal_update() { - if (levels_[0] == 0) { compress_while_updating(); } + if (levels_[0] == 0) { + if (items_size_ < k_) { + grow_items(); + } else { + compress_while_updating(); + } + } n_++; is_level_zero_sorted_ = false; return --levels_[0]; @@ -390,7 +396,11 @@ void kll_sketch::serialize(std::ostream& os, const SerDe& sd) const { write(os, min_k_); write(os, num_levels_); write(os, unused); - write(os, levels_.data(), sizeof(levels_[0]) * num_levels_); + if (items_size_ < k_) { + write(os, levels_[0] + (k_ - items_size_)); + } else { + write(os, levels_.data(), sizeof(levels_[0]) * num_levels_); + } sd.serialize(os, &*min_item_, 1); sd.serialize(os, &*max_item_, 1); } @@ -426,7 +436,11 @@ auto kll_sketch::serialize(unsigned header_size_bytes, const SerDe& sd) ptr += copy_to_mem(min_k_, ptr); ptr += copy_to_mem(num_levels_, ptr); ptr += sizeof(uint8_t); // unused - ptr += copy_to_mem(levels_.data(), ptr, sizeof(levels_[0]) * num_levels_); + if (items_size_ < k_) { + ptr += copy_to_mem(levels_[0] + (k_ - items_size_), ptr); + } else { + ptr += copy_to_mem(levels_.data(), ptr, sizeof(levels_[0]) * num_levels_); + } ptr += sd.serialize(ptr, end_ptr - ptr, &*min_item_, 1); ptr += sd.serialize(ptr, end_ptr - ptr, &*max_item_, 1); } @@ -754,6 +768,21 @@ void kll_sketch::add_empty_top_level_to_completely_full_sketch() { levels_[num_levels_] = new_total_cap; // initialize the new "extra" index at the top } +// Grows the items buffer of a one-level sketch when it is full and smaller than k. +// Compaction starts only when the buffer is full at k items, so growing does not change the result. +template +void kll_sketch::grow_items() { + const uint32_t new_size = std::min(items_size_ << static_cast(RESIZE_FACTOR), k_); + const uint32_t delta = new_size - items_size_; + T* new_items = allocator_.allocate(new_size); + kll_helper::move_construct(items_, levels_[0], levels_[1], new_items, levels_[0] + delta, true); + allocator_.deallocate(items_, items_size_); + items_ = new_items; + items_size_ = new_size; + levels_[0] += delta; + levels_[1] += delta; +} + template void kll_sketch::sort_level_zero() { if (!is_level_zero_sorted_) { @@ -961,7 +990,8 @@ string kll_sketch::to_string(bool print_levels, bool print_items) co os << " Estimation mode: " << (is_estimation_mode() ? "true" : "false") << std::endl; os << " Levels : " << (unsigned int) num_levels_ << std::endl; os << " Sorted : " << (is_level_zero_sorted_ ? "true" : "false") << std::endl; - os << " Capacity items : " << items_size_ << std::endl; + // a buffer still growing to k items shows the capacity of a full one + os << " Capacity items : " << std::max(items_size_, k_) << std::endl; os << " Retained items : " << get_num_retained() << std::endl; if (!is_empty()) { os << " Min item : " << *min_item_ << std::endl; diff --git a/kll/test/kll_sketch_test.cpp b/kll/test/kll_sketch_test.cpp index 05eea991..7991735a 100644 --- a/kll/test/kll_sketch_test.cpp +++ b/kll/test/kll_sketch_test.cpp @@ -18,11 +18,13 @@ */ #include +#include #include #include #include #include #include +#include #include #include @@ -915,4 +917,215 @@ TEST_CASE("kll sketch: deserialize rejects inconsistent levels", "[kll_sketch]") } } +// A deserialized sketch has a buffer of the full size. +template +static Sketch with_full_buffer(const Sketch& sketch) { + auto bytes = sketch.serialize(); + return Sketch::deserialize(bytes.data(), bytes.size(), serde(), + sketch.get_comparator(), sketch.get_allocator()); +} + +// Applies fn to both sketches with the same random bits, so that they compact the same way. +template +static void apply_to_both(Sketch& growing, Sketch& full, const Fn& fn) { + const auto random_bit = random_utils::random_bit; + fn(growing); + random_utils::random_bit = random_bit; + fn(full); +} + +template +static std::vector> items_and_weights(const Sketch& sketch) { + std::vector> result; + for (const auto pair: sketch) { result.emplace_back(pair.first, pair.second); } + return result; +} + +// Requires the same retained items and weights, the same query results and the same bytes. +template +static void require_identical(const Sketch& growing, const Sketch& full) { + REQUIRE(growing.get_n() == full.get_n()); + REQUIRE(growing.get_num_retained() == full.get_num_retained()); + REQUIRE(growing.is_estimation_mode() == full.is_estimation_mode()); + REQUIRE(growing.get_normalized_rank_error(false) == full.get_normalized_rank_error(false)); + REQUIRE(growing.get_normalized_rank_error(true) == full.get_normalized_rank_error(true)); + REQUIRE(items_and_weights(growing) == items_and_weights(full)); + if (!growing.is_empty()) { + REQUIRE(growing.get_min_item() == full.get_min_item()); + REQUIRE(growing.get_max_item() == full.get_max_item()); + std::vector split_points; + for (int i = 0; i <= 100; ++i) { + const double rank = i / 100.0; + for (const bool inclusive: {false, true}) { + const auto quantile = growing.get_quantile(rank, inclusive); + REQUIRE(quantile == full.get_quantile(rank, inclusive)); + REQUIRE(growing.get_rank(quantile, inclusive) == full.get_rank(quantile, inclusive)); + } + split_points.push_back(growing.get_quantile(rank)); + } + split_points.erase(std::unique(split_points.begin(), split_points.end()), split_points.end()); + for (const bool inclusive: {false, true}) { + REQUIRE(growing.get_PMF(split_points.data(), split_points.size(), inclusive) + == full.get_PMF(split_points.data(), split_points.size(), inclusive)); + REQUIRE(growing.get_CDF(split_points.data(), split_points.size(), inclusive) + == full.get_CDF(split_points.data(), split_points.size(), inclusive)); + } + } + REQUIRE(growing.serialize() == full.serialize()); + std::stringstream growing_stream, full_stream; + growing.serialize(growing_stream); + full.serialize(full_stream); + REQUIRE(growing_stream.str() == full_stream.str()); + REQUIRE(growing.to_string(true, false) == full.to_string(true, false)); +} + +// Sizes of the items buffer as it grows by 8x up to k. +static std::vector buffer_sizes(uint16_t k) { + std::vector sizes = {std::min(k, kll_constants::DEFAULT_K)}; + while (sizes.back() < k) { + sizes.push_back(std::min(sizes.back() * 8, k)); + } + return sizes; +} + +// Updates a sketch and a copy of it with a full buffer the same way, and requires the same results. +template +static void require_same_as_full_buffer(Sketch& growing, uint32_t num_items) { + auto full = with_full_buffer(growing); + random_utils::random_bit.seed(4); + for (uint32_t i = 0; i < num_items; ++i) { + const auto item = static_cast(i % 7777); + apply_to_both(growing, full, [&item](Sketch& sketch) { sketch.update(item); }); + if (i == 1000 || i == 20000) { require_identical(growing, full); } + } + require_identical(growing, full); +} + +TEST_CASE("kll sketch: lazy growth of the items buffer", "[kll_sketch]") { + test_allocator_total_bytes = 0; + const long long levels_bytes = 2 * sizeof(uint32_t); + + SECTION("k below DEFAULT_K allocates k items") { + const uint16_t k = kll_constants::DEFAULT_K / 2; + kll_float_sketch sketch(k, std::less(), 0); + sketch.update(0); + REQUIRE(test_allocator_total_bytes == static_cast(levels_bytes + k * sizeof(float))); + for (int i = 1; i < k; ++i) { sketch.update(static_cast(i)); } + REQUIRE(test_allocator_total_bytes == static_cast(levels_bytes + k * sizeof(float))); + } + + SECTION("buffer grows by 8x up to k") { + REQUIRE(buffer_sizes(kll_constants::MAX_K) == std::vector{200, 1600, 12800, 65535}); + kll_float_sketch sketch(kll_constants::MAX_K, std::less(), 0); + REQUIRE(test_allocator_total_bytes + == static_cast(levels_bytes + kll_constants::DEFAULT_K * sizeof(float))); + uint32_t n = 0; + for (const uint32_t size: buffer_sizes(kll_constants::MAX_K)) { + while (n < size) { + sketch.update(static_cast(n++)); + // the buffer grows when an item does not fit + REQUIRE(test_allocator_total_bytes == static_cast(levels_bytes + size * sizeof(float))); + } + } + REQUIRE_FALSE(sketch.is_estimation_mode()); + sketch.update(0); + REQUIRE(sketch.is_estimation_mode()); + } + + SECTION("merge grows the buffer like updates") { + kll_float_sketch other(kll_constants::MAX_K, std::less(), 0); + for (int i = 0; i < 1000; ++i) { other.update(static_cast(i)); } + const long long other_bytes = test_allocator_total_bytes; + kll_float_sketch sketch(kll_constants::MAX_K, std::less(), 0); + sketch.merge(other); + REQUIRE(test_allocator_total_bytes - other_bytes == static_cast(levels_bytes + 1600 * sizeof(float))); + REQUIRE(sketch.get_n() == 1000); + } + + SECTION("same as a full buffer through compactions") { + // the buffer grows 1, 2 and 3 times before it reaches these k + const uint16_t ks[] = {201, 5000, 20000}; + for (const uint16_t k: ks) { + random_utils::random_bit.seed(k); + kll_float_sketch growing(k, std::less(), 0); + growing.update(0); + const long long growing_bytes = test_allocator_total_bytes; + kll_float_sketch full = with_full_buffer(growing); + REQUIRE(test_allocator_total_bytes - growing_bytes == static_cast(levels_bytes + k * sizeof(float))); + const auto sizes = buffer_sizes(k); + for (uint32_t n = 2; n <= 10u * k; ++n) { + const float item = static_cast((n * 7919) % 10007) / 3; + apply_to_both(growing, full, [item](kll_float_sketch& sketch) { sketch.update(item); }); + const bool at_growth = std::find(sizes.begin(), sizes.end(), n) != sizes.end() + || std::find(sizes.begin(), sizes.end(), n - 1) != sizes.end(); + if (at_growth || n % 997 == 0 || n % k <= 1) { require_identical(growing, full); } + } + REQUIRE(growing.is_estimation_mode()); + require_identical(growing, full); + } + } + + SECTION("same as a full buffer when merging") { + random_utils::random_bit.seed(3); + // exact mode sketches first, so that merging grows the buffer before compactions start + const std::vector> k_and_n = { + {30000, 1000}, {30000, 3000}, {20000, 15000}, {2000, 10000}, {8, 100}, {20000, 60000}}; + std::vector others; + for (const auto& shape: k_and_n) { + others.emplace_back(shape.first, std::less(), 0); + for (uint32_t i = 0; i < shape.second; ++i) { others.back().update(static_cast((i * 31) % 4999)); } + } + for (const bool reversed: {false, true}) { + kll_float_sketch growing(20000, std::less(), 0); + growing.update(0); + kll_float_sketch full = with_full_buffer(growing); + for (size_t i = 0; i < others.size(); ++i) { + const auto& other = others[reversed ? others.size() - 1 - i : i]; + apply_to_both(growing, full, [&other](kll_float_sketch& sketch) { sketch.merge(other); }); + require_identical(growing, full); + } + for (int i = 0; i < 50000; ++i) { + apply_to_both(growing, full, [i](kll_float_sketch& sketch) { sketch.update(static_cast(i)); }); + } + require_identical(growing, full); + } + } + + SECTION("copies, moves and converted sketches keep growing the same") { + kll_float_sketch sketch(kll_constants::MAX_K, std::less(), 0); + for (int i = 0; i < 500; ++i) { sketch.update(static_cast(i)); } + kll_float_sketch copied(sketch); + kll_float_sketch assigned(8, std::less(), 0); + assigned = sketch; + kll_float_sketch to_move(sketch); + kll_float_sketch moved(std::move(to_move)); + kll_float_sketch move_assigned(8, std::less(), 0); + kll_float_sketch to_move_assign(sketch); + move_assigned = std::move(to_move_assign); + for (auto* growing: {&sketch, &copied, &assigned, &moved, &move_assigned}) { + require_same_as_full_buffer(*growing, 200000); + } + kll_float_sketch source(kll_constants::MAX_K, std::less(), 0); + for (int i = 0; i < 500; ++i) { source.update(static_cast(i)); } + kll_sketch, test_allocator> converted(source, std::less(), 0); + require_same_as_full_buffer(converted, 200000); + } + + SECTION("same as a full buffer with strings") { + random_utils::random_bit.seed(5); + kll_string_sketch growing(5000, std::less(), 0); + growing.update("0"); + kll_string_sketch full = with_full_buffer(growing); + for (int i = 1; i < 30000; ++i) { + const std::string item = std::to_string((i * 7919) % 10007); + apply_to_both(growing, full, [&item](kll_string_sketch& sketch) { sketch.update(item); }); + if (i == 199 || i == 200 || i == 1599 || i == 1600 || i == 4999 || i == 10000) { require_identical(growing, full); } + } + require_identical(growing, full); + } + + // cleanup + REQUIRE(test_allocator_total_bytes == 0); +} + } /* namespace datasketches */ From e8822c5aa06c168653c5822d1397aa4bb8a970cc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Milo=C5=A1=20Stojko?= Date: Tue, 10 Nov 2026 09:56:37 +0000 Subject: [PATCH 2/7] KLL: address review: one-level guard and cross-language files Write the growing-buffer level offset only for a one-level sketch, and generate float, double, long and string files with k = 65535 and n up to 10000, while the items buffer still grows. Co-authored-by: Isaac --- kll/include/kll_sketch_impl.hpp | 4 +-- kll/test/kll_sketch_serialize_for_java.cpp | 41 ++++++++++++++++++++++ 2 files changed, 43 insertions(+), 2 deletions(-) diff --git a/kll/include/kll_sketch_impl.hpp b/kll/include/kll_sketch_impl.hpp index ffd3af20..4cd1afad 100644 --- a/kll/include/kll_sketch_impl.hpp +++ b/kll/include/kll_sketch_impl.hpp @@ -396,7 +396,7 @@ void kll_sketch::serialize(std::ostream& os, const SerDe& sd) const { write(os, min_k_); write(os, num_levels_); write(os, unused); - if (items_size_ < k_) { + if (num_levels_ == 1 && items_size_ < k_) { write(os, levels_[0] + (k_ - items_size_)); } else { write(os, levels_.data(), sizeof(levels_[0]) * num_levels_); @@ -436,7 +436,7 @@ auto kll_sketch::serialize(unsigned header_size_bytes, const SerDe& sd) ptr += copy_to_mem(min_k_, ptr); ptr += copy_to_mem(num_levels_, ptr); ptr += sizeof(uint8_t); // unused - if (items_size_ < k_) { + if (num_levels_ == 1 && items_size_ < k_) { ptr += copy_to_mem(levels_[0] + (k_ - items_size_), ptr); } else { ptr += copy_to_mem(levels_.data(), ptr, sizeof(levels_[0]) * num_levels_); diff --git a/kll/test/kll_sketch_serialize_for_java.cpp b/kll/test/kll_sketch_serialize_for_java.cpp index 22b75774..cd79e918 100644 --- a/kll/test/kll_sketch_serialize_for_java.cpp +++ b/kll/test/kll_sketch_serialize_for_java.cpp @@ -69,4 +69,45 @@ TEST_CASE("kll sketch string generate", "[serialize_for_java]") { } } +// with k = 65535, the items buffer is still growing at these n +TEST_CASE("kll sketch float generate, k = 65535", "[serialize_for_java]") { + const unsigned n_arr[] = {0, 1, 10, 100, 1000, 10000}; + for (const unsigned n: n_arr) { + kll_sketch sketch(kll_constants::MAX_K); + for (unsigned i = 1; i <= n; ++i) sketch.update(i); + std::ofstream os("kll_float_k65535_n" + std::to_string(n) + "_cpp.sk", std::ios::binary); + sketch.serialize(os); + } +} + +TEST_CASE("kll sketch double generate, k = 65535", "[serialize_for_java]") { + const unsigned n_arr[] = {0, 1, 10, 100, 1000, 10000}; + for (const unsigned n: n_arr) { + kll_sketch sketch(kll_constants::MAX_K); + for (unsigned i = 1; i <= n; ++i) sketch.update(i); + std::ofstream os("kll_double_k65535_n" + std::to_string(n) + "_cpp.sk", std::ios::binary); + sketch.serialize(os); + } +} + +TEST_CASE("kll sketch long generate, k = 65535", "[serialize_for_java]") { + const unsigned n_arr[] = {0, 1, 10, 100, 1000, 10000}; + for (const unsigned n: n_arr) { + kll_sketch sketch(kll_constants::MAX_K); + for (unsigned i = 1; i <= n; ++i) sketch.update(i); + std::ofstream os("kll_long_k65535_n" + std::to_string(n) + "_cpp.sk", std::ios::binary); + sketch.serialize(os); + } +} + +TEST_CASE("kll sketch string generate, k = 65535", "[serialize_for_java]") { + const unsigned n_arr[] = {0, 1, 10, 100, 1000, 10000}; + for (const unsigned n: n_arr) { + kll_sketch sketch(kll_constants::MAX_K); + for (unsigned i = 1; i <= n; ++i) sketch.update(std::to_string(i)); + std::ofstream os("kll_string_k65535_n" + std::to_string(n) + "_cpp.sk", std::ios::binary); + sketch.serialize(os); + } +} + } /* namespace datasketches */ From 6694d3d33b04044285cb297adcc9a488cb4ef732 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Milo=C5=A1=20Stojko?= Date: Wed, 11 Nov 2026 06:04:34 +0000 Subject: [PATCH 3/7] KLL: add n = 12801, where growth is capped at k, to the k = 65535 cross-language files Co-authored-by: Isaac --- kll/test/kll_sketch_serialize_for_java.cpp | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/kll/test/kll_sketch_serialize_for_java.cpp b/kll/test/kll_sketch_serialize_for_java.cpp index cd79e918..6af82751 100644 --- a/kll/test/kll_sketch_serialize_for_java.cpp +++ b/kll/test/kll_sketch_serialize_for_java.cpp @@ -69,9 +69,9 @@ TEST_CASE("kll sketch string generate", "[serialize_for_java]") { } } -// with k = 65535, the items buffer is still growing at these n +// with k = 65535, the buffer is still growing up to n = 10000, and n = 12801 caps its growth at k TEST_CASE("kll sketch float generate, k = 65535", "[serialize_for_java]") { - const unsigned n_arr[] = {0, 1, 10, 100, 1000, 10000}; + const unsigned n_arr[] = {0, 1, 10, 100, 1000, 10000, 12801}; for (const unsigned n: n_arr) { kll_sketch sketch(kll_constants::MAX_K); for (unsigned i = 1; i <= n; ++i) sketch.update(i); @@ -81,7 +81,7 @@ TEST_CASE("kll sketch float generate, k = 65535", "[serialize_for_java]") { } TEST_CASE("kll sketch double generate, k = 65535", "[serialize_for_java]") { - const unsigned n_arr[] = {0, 1, 10, 100, 1000, 10000}; + const unsigned n_arr[] = {0, 1, 10, 100, 1000, 10000, 12801}; for (const unsigned n: n_arr) { kll_sketch sketch(kll_constants::MAX_K); for (unsigned i = 1; i <= n; ++i) sketch.update(i); @@ -91,7 +91,7 @@ TEST_CASE("kll sketch double generate, k = 65535", "[serialize_for_java]") { } TEST_CASE("kll sketch long generate, k = 65535", "[serialize_for_java]") { - const unsigned n_arr[] = {0, 1, 10, 100, 1000, 10000}; + const unsigned n_arr[] = {0, 1, 10, 100, 1000, 10000, 12801}; for (const unsigned n: n_arr) { kll_sketch sketch(kll_constants::MAX_K); for (unsigned i = 1; i <= n; ++i) sketch.update(i); @@ -101,7 +101,7 @@ TEST_CASE("kll sketch long generate, k = 65535", "[serialize_for_java]") { } TEST_CASE("kll sketch string generate, k = 65535", "[serialize_for_java]") { - const unsigned n_arr[] = {0, 1, 10, 100, 1000, 10000}; + const unsigned n_arr[] = {0, 1, 10, 100, 1000, 10000, 12801}; for (const unsigned n: n_arr) { kll_sketch sketch(kll_constants::MAX_K); for (unsigned i = 1; i <= n; ++i) sketch.update(std::to_string(i)); From 91f4d66b4fc0e0d28045c4b9b63856c240cff2b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Milo=C5=A1=20Stojko?= Date: Wed, 11 Nov 2026 06:21:33 +0000 Subject: [PATCH 4/7] KLL: add k = 1000 to the cross-language files and the lockstep test Co-authored-by: Isaac --- kll/test/kll_sketch_serialize_for_java.cpp | 41 ++++++++++++++++++++++ kll/test/kll_sketch_test.cpp | 4 +-- 2 files changed, 43 insertions(+), 2 deletions(-) diff --git a/kll/test/kll_sketch_serialize_for_java.cpp b/kll/test/kll_sketch_serialize_for_java.cpp index 6af82751..c76f1c08 100644 --- a/kll/test/kll_sketch_serialize_for_java.cpp +++ b/kll/test/kll_sketch_serialize_for_java.cpp @@ -69,6 +69,47 @@ TEST_CASE("kll sketch string generate", "[serialize_for_java]") { } } +// with k = 1000, the buffer holds 200 items up to n = 200, and n = 201 caps its growth at k +TEST_CASE("kll sketch float generate, k = 1000", "[serialize_for_java]") { + const unsigned n_arr[] = {0, 1, 10, 100, 200, 201, 1000}; + for (const unsigned n: n_arr) { + kll_sketch sketch(1000); + for (unsigned i = 1; i <= n; ++i) sketch.update(i); + std::ofstream os("kll_float_k1000_n" + std::to_string(n) + "_cpp.sk", std::ios::binary); + sketch.serialize(os); + } +} + +TEST_CASE("kll sketch double generate, k = 1000", "[serialize_for_java]") { + const unsigned n_arr[] = {0, 1, 10, 100, 200, 201, 1000}; + for (const unsigned n: n_arr) { + kll_sketch sketch(1000); + for (unsigned i = 1; i <= n; ++i) sketch.update(i); + std::ofstream os("kll_double_k1000_n" + std::to_string(n) + "_cpp.sk", std::ios::binary); + sketch.serialize(os); + } +} + +TEST_CASE("kll sketch long generate, k = 1000", "[serialize_for_java]") { + const unsigned n_arr[] = {0, 1, 10, 100, 200, 201, 1000}; + for (const unsigned n: n_arr) { + kll_sketch sketch(1000); + for (unsigned i = 1; i <= n; ++i) sketch.update(i); + std::ofstream os("kll_long_k1000_n" + std::to_string(n) + "_cpp.sk", std::ios::binary); + sketch.serialize(os); + } +} + +TEST_CASE("kll sketch string generate, k = 1000", "[serialize_for_java]") { + const unsigned n_arr[] = {0, 1, 10, 100, 200, 201, 1000}; + for (const unsigned n: n_arr) { + kll_sketch sketch(1000); + for (unsigned i = 1; i <= n; ++i) sketch.update(std::to_string(i)); + std::ofstream os("kll_string_k1000_n" + std::to_string(n) + "_cpp.sk", std::ios::binary); + sketch.serialize(os); + } +} + // with k = 65535, the buffer is still growing up to n = 10000, and n = 12801 caps its growth at k TEST_CASE("kll sketch float generate, k = 65535", "[serialize_for_java]") { const unsigned n_arr[] = {0, 1, 10, 100, 1000, 10000, 12801}; diff --git a/kll/test/kll_sketch_test.cpp b/kll/test/kll_sketch_test.cpp index 7991735a..3e2caa3a 100644 --- a/kll/test/kll_sketch_test.cpp +++ b/kll/test/kll_sketch_test.cpp @@ -1043,8 +1043,8 @@ TEST_CASE("kll sketch: lazy growth of the items buffer", "[kll_sketch]") { } SECTION("same as a full buffer through compactions") { - // the buffer grows 1, 2 and 3 times before it reaches these k - const uint16_t ks[] = {201, 5000, 20000}; + // the buffer grows once (k = 201 and 1000), twice (5000) or three times (20000) before k + const uint16_t ks[] = {201, 1000, 5000, 20000}; for (const uint16_t k: ks) { random_utils::random_bit.seed(k); kll_float_sketch growing(k, std::less(), 0); From 0ad21a2bd9d1d0e7a673c08f02db73d75900fba6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Milo=C5=A1=20Stojko?= Date: Wed, 11 Nov 2026 06:27:19 +0000 Subject: [PATCH 5/7] KLL: keep the lockstep test as before, without k = 1000 Co-authored-by: Isaac --- kll/test/kll_sketch_test.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/kll/test/kll_sketch_test.cpp b/kll/test/kll_sketch_test.cpp index 3e2caa3a..7991735a 100644 --- a/kll/test/kll_sketch_test.cpp +++ b/kll/test/kll_sketch_test.cpp @@ -1043,8 +1043,8 @@ TEST_CASE("kll sketch: lazy growth of the items buffer", "[kll_sketch]") { } SECTION("same as a full buffer through compactions") { - // the buffer grows once (k = 201 and 1000), twice (5000) or three times (20000) before k - const uint16_t ks[] = {201, 1000, 5000, 20000}; + // the buffer grows 1, 2 and 3 times before it reaches these k + const uint16_t ks[] = {201, 5000, 20000}; for (const uint16_t k: ks) { random_utils::random_bit.seed(k); kll_float_sketch growing(k, std::less(), 0); From cba154b3853a0846429cb65d51470e6284dbe5a9 Mon Sep 17 00:00:00 2001 From: Lee Rhodes Date: Sun, 15 Nov 2026 15:48:01 -0800 Subject: [PATCH 6/7] KLL: reserve() after updates grows the buffer to k items Before the first compaction, a buffer that is still growing is grown to k items in one step, so reserve() means the same before and after the first update: the buffer does not need to grow before the first compaction. As noted in review. Co-Authored-By: Claude Opus 5.5 --- kll/include/kll_sketch.hpp | 10 +++++----- kll/include/kll_sketch_impl.hpp | 18 ++++++++++-------- kll/test/kll_sketch_test.cpp | 18 ++++++++++++++---- 3 files changed, 29 insertions(+), 17 deletions(-) diff --git a/kll/include/kll_sketch.hpp b/kll/include/kll_sketch.hpp index a647196d..5359af19 100644 --- a/kll/include/kll_sketch.hpp +++ b/kll/include/kll_sketch.hpp @@ -261,11 +261,11 @@ class kll_sketch { void merge(FwdSk&& other); /** - * Allocates storage for k items now, rather than on the first update or merge. - * The buffer then does not need to grow before the first compaction. + * Allocates storage for k items now, rather than on the first update or merge, + * or as the buffer grows. The buffer then does not need to grow before the first compaction. * Call this right after construction if allocation failures should happen here, - * or if the first update should not pay for the allocation. - * Does nothing if the storage is already allocated. + * or if updates should not pay for the allocation. + * Does nothing if the storage for k items is already allocated. * @throw std::bad_alloc if the allocation fails, in which case the sketch is unchanged */ void reserve(); @@ -616,7 +616,7 @@ class kll_sketch { uint8_t find_level_to_compact() const; void add_empty_top_level_to_completely_full_sketch(); - void grow_items(); + void grow_items(uint32_t new_size); // only while there is one level void sort_level_zero(); template void merge_higher_levels(O&& other, uint64_t final_n); diff --git a/kll/include/kll_sketch_impl.hpp b/kll/include/kll_sketch_impl.hpp index 85911e53..bb3dbd82 100644 --- a/kll/include/kll_sketch_impl.hpp +++ b/kll/include/kll_sketch_impl.hpp @@ -206,11 +206,14 @@ void kll_sketch::update_min_max(const T& item) { template void kll_sketch::reserve() { - if (items_ != nullptr) return; - // nothing is stored yet, so the buffer can start at its full size - items_ = allocator_.allocate(k_); - items_size_ = k_; - levels_[0] = levels_[1] = k_; + if (items_ == nullptr) { + // nothing is stored yet, so the buffer can start at its full size + items_ = allocator_.allocate(k_); + items_size_ = k_; + levels_[0] = levels_[1] = k_; + } else if (num_levels_ == 1 && items_size_ < k_) { + grow_items(k_); // the buffer is still growing: grow it to its full size in one step + } } template @@ -236,7 +239,7 @@ uint32_t kll_sketch::internal_update() { allocate_items(); if (levels_[0] == 0) { if (items_size_ < k_) { - grow_items(); + grow_items(std::min(items_size_ << static_cast(RESIZE_FACTOR), k_)); } else { compress_while_updating(); } @@ -807,8 +810,7 @@ void kll_sketch::add_empty_top_level_to_completely_full_sketch() { // Grows the items buffer of a one-level sketch when it is full and smaller than k. // Compaction starts only when the buffer is full at k items, so growing does not change the result. template -void kll_sketch::grow_items() { - const uint32_t new_size = std::min(items_size_ << static_cast(RESIZE_FACTOR), k_); +void kll_sketch::grow_items(uint32_t new_size) { const uint32_t delta = new_size - items_size_; T* new_items = allocator_.allocate(new_size); kll_helper::move_construct(items_, levels_[0], levels_[1], new_items, levels_[0] + delta, true); diff --git a/kll/test/kll_sketch_test.cpp b/kll/test/kll_sketch_test.cpp index 5d31f162..2ccab79a 100644 --- a/kll/test/kll_sketch_test.cpp +++ b/kll/test/kll_sketch_test.cpp @@ -1142,13 +1142,23 @@ TEST_CASE("kll sketch: lazy growth of the items buffer", "[kll_sketch]") { REQUIRE_FALSE(sketch.is_estimation_mode()); } - SECTION("reserve() after the first update does nothing") { + SECTION("reserve() after updates grows the buffer to k items") { kll_float_sketch sketch(kll_constants::MAX_K, std::less(), 0); - sketch.update(0); - const long long bytes = test_allocator_total_bytes; - REQUIRE(bytes == static_cast(levels_bytes + kll_constants::DEFAULT_K * sizeof(float))); + for (int i = 0; i < 10; ++i) sketch.update(static_cast(i)); + REQUIRE(test_allocator_total_bytes == static_cast(levels_bytes + kll_constants::DEFAULT_K * sizeof(float))); sketch.reserve(); + const long long bytes = test_allocator_total_bytes; + REQUIRE(bytes == static_cast(levels_bytes + kll_constants::MAX_K * sizeof(float))); + REQUIRE(sketch.get_n() == 10); + REQUIRE(sketch.get_min_item() == 0); + REQUIRE(sketch.get_max_item() == 9); + for (const auto pair: sketch) REQUIRE(pair.second == 1); + for (int i = 10; i < kll_constants::MAX_K; ++i) sketch.update(static_cast(i)); + REQUIRE(test_allocator_total_bytes == bytes); // no growth before the first compaction + sketch.reserve(); // the buffer is already at k items REQUIRE(test_allocator_total_bytes == bytes); + REQUIRE_FALSE(sketch.is_estimation_mode()); + REQUIRE(sketch.get_rank(100) == Approx(101.0 / kll_constants::MAX_K)); // inclusive } SECTION("same as a full buffer after reserve()") { From ec1a37c8aa8628dd292d4a1ab627c2ec7c388d3d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Milo=C5=A1=20Stojko?= Date: Tue, 17 Nov 2026 18:54:39 +0000 Subject: [PATCH 7/7] KLL: reserve() resets the sorted view after it grows the buffer For non-arithmetic items, the cached sorted view holds pointers into the items buffer, and growing the buffer frees it. A query after reserve() then read freed memory. Co-authored-by: Isaac --- kll/include/kll_sketch_impl.hpp | 1 + kll/test/kll_sketch_test.cpp | 12 ++++++++++++ 2 files changed, 13 insertions(+) diff --git a/kll/include/kll_sketch_impl.hpp b/kll/include/kll_sketch_impl.hpp index bb3dbd82..701c789a 100644 --- a/kll/include/kll_sketch_impl.hpp +++ b/kll/include/kll_sketch_impl.hpp @@ -213,6 +213,7 @@ void kll_sketch::reserve() { levels_[0] = levels_[1] = k_; } else if (num_levels_ == 1 && items_size_ < k_) { grow_items(k_); // the buffer is still growing: grow it to its full size in one step + reset_sorted_view(); // the cached view points into the old buffer } } diff --git a/kll/test/kll_sketch_test.cpp b/kll/test/kll_sketch_test.cpp index 2ccab79a..2cf4bbdb 100644 --- a/kll/test/kll_sketch_test.cpp +++ b/kll/test/kll_sketch_test.cpp @@ -1187,6 +1187,18 @@ TEST_CASE("kll sketch: lazy growth of the items buffer", "[kll_sketch]") { REQUIRE(test_allocator_total_bytes == 0); } +// The sorted view of a string sketch points into the items buffer, which reserve() can replace +TEST_CASE("kll sketch: reserve() after a query", "[kll_sketch]") { + kll_sketch sketch(5000); // the buffer starts at 200 items + for (int i = 0; i < 100; ++i) sketch.update(std::string(64, 'x') + std::to_string(1000 + i)); + const std::string item = std::string(64, 'x') + "1050"; + const double rank = sketch.get_rank(item); // caches the sorted view + const std::string median = sketch.get_quantile(0.5); + sketch.reserve(); // grows the buffer + REQUIRE(sketch.get_rank(item) == rank); + REQUIRE(sketch.get_quantile(0.5) == median); +} + // Compaction: level 0 is full, so update(item) compacts it, which can free the item it reads TEST_CASE("kll sketch: update with aliased item during compaction", "[kll_sketch]") { const uint16_t k = 200;