Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 30 additions & 2 deletions kll/include/kll_sketch.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,13 @@ namespace kll_constants {
* <li>Then <i>q<sub>lo</sub> &le; q &le; q<sub>hi</sub></i>, with 99% confidence.</li>
* </ul>
*
* <p>Memory allocation: a new sketch does not allocate storage for items until it first needs it,
* on the first update or the first merge of a non-empty sketch. Sketches that stay empty, or that
* are only ever merged into, use little memory. As a result, the first update or merge can throw
* std::bad_alloc while allocating this storage, rather than the constructor. If that happens, the
* sketch is unchanged and can still be used. Call reserve() right after construction to allocate
* the storage up front.
*
* author Kevin Lang
* author Alexander Saydakov
* author Lee Rhodes
Expand All @@ -183,7 +190,8 @@ class kll_sketch {
using quantile_return_type = typename quantiles_sorted_view<T, C, A>::quantile_return_type;

/**
* Constructor
* Constructor.
* Storage for items is allocated on first use, see reserve().
* @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
Expand Down Expand Up @@ -232,6 +240,7 @@ class kll_sketch {
* Updates this sketch with the given data item.
* If cross-language portability is required, callers should ensure that
* the input string uses a compatible encoding (valid UTF-8).
* The first update allocates storage for items, unless reserve() or a merge already did.
* @param item from a stream of items
*/
template<typename FwdT>
Expand All @@ -242,11 +251,22 @@ class kll_sketch {
* If sketches contain strings, callers are responsible for ensuring that
* both sketches were built using compatible string encodings.
* If other is this sketch, this throws std::invalid_argument.
* The first merge of a non-empty sketch allocates storage for items,
* unless reserve() or an update already did.
* @param other sketch to merge into this one
*/
template<typename FwdSk>
void merge(FwdSk&& other);

/**
* Allocates storage for items now, rather than on the first update or merge.
* 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.
* @throw std::bad_alloc if the allocation fails, in which case the sketch is unchanged
*/
void reserve();

/**
* Returns true if this sketch is empty.
* @return empty flag
Expand Down Expand Up @@ -522,6 +542,7 @@ class kll_sketch {

/**
* Gets the sorted view of this sketch
* An empty sketch returns an empty view without allocating item storage.
* @return the sorted view of this sketch
*/
quantiles_sorted_view<T, C, A> get_sorted_view() const;
Expand Down Expand Up @@ -559,7 +580,7 @@ class kll_sketch {
bool is_level_zero_sorted_;
uint64_t n_;
vector_u32 levels_;
T* items_;
T* items_; // nullptr until the sketch first receives items, see allocate_items()
uint32_t items_size_;
optional<T> min_item_;
optional<T> max_item_;
Expand All @@ -573,6 +594,13 @@ class kll_sketch {

// common update code
inline void update_min_max(const T& item);
// items_ is allocated lazily, and these are the only places that deal with it being nullptr:
// allocates items_ (items_size_ items) unless it is allocated already
inline void allocate_items();
// copy-constructs the items of other, if other has any, into this newly constructed sketch
template<typename O> void copy_items(const O& other);
// &items_[index], or nullptr without item storage, which makes every item range empty
inline T* item_ptr(uint32_t index) const;
inline uint32_t internal_update();

// The following code is only valid in the special case of exactly reaching capacity while updating.
Expand Down
45 changes: 35 additions & 10 deletions kll/include/kll_sketch_impl.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,8 @@ sorted_view_(nullptr)
+ std::to_string(kll_constants::MAX_K) + ": " + std::to_string(k));
}
levels_[0] = levels_[1] = k;
items_ = allocator_.allocate(items_size_);
// items_ is allocated by the first update or merge: many sketches (e.g. per-group aggregation states)
// stay empty or are only ever merged into
}

template<typename T, typename C, typename A>
Expand All @@ -75,8 +76,7 @@ min_item_(other.min_item_),
max_item_(other.max_item_),
sorted_view_(nullptr)
{
items_ = allocator_.allocate(items_size_);
for (auto i = levels_[0]; i < levels_[num_levels_]; ++i) new (&items_[i]) T(other.items_[i]);
copy_items(other);
}

template<typename T, typename C, typename A>
Expand Down Expand Up @@ -171,15 +171,15 @@ sorted_view_(nullptr)
std::is_constructible<T, TT>::value,
"Type converting constructor requires new type to be constructible from existing type"
);
items_ = allocator_.allocate(items_size_);
for (auto i = levels_[0]; i < levels_[num_levels_]; ++i) new (&items_[i]) T(other.items_[i]);
copy_items(other);
check_sorting();
}

template<typename T, typename C, typename A>
template<typename FwdT>
void kll_sketch<T, C, A>::update(FwdT&& item) {
if (!check_update_item(item)) { return; }
allocate_items(); // first, so that a failure leaves the sketch unchanged
update_min_max(static_cast<const T&>(item)); // min and max are always copies
const uint32_t index = internal_update();
new (&items_[index]) T(std::forward<FwdT>(item));
Expand All @@ -197,8 +197,32 @@ void kll_sketch<T, C, A>::update_min_max(const T& item) {
}
}

template<typename T, typename C, typename A>
void kll_sketch<T, C, A>::reserve() {
allocate_items();
}

template<typename T, typename C, typename A>
void kll_sketch<T, C, A>::allocate_items() {
if (items_ == nullptr) items_ = allocator_.allocate(items_size_);
}

template<typename T, typename C, typename A>
template<typename O>
void kll_sketch<T, C, A>::copy_items(const O& other) {
if (other.items_ == nullptr) return;
allocate_items();
for (auto i = levels_[0]; i < levels_[num_levels_]; ++i) new (&items_[i]) T(other.items_[i]);
}

template<typename T, typename C, typename A>
T* kll_sketch<T, C, A>::item_ptr(uint32_t index) const {
return items_ == nullptr ? nullptr : items_ + index;
}

template<typename T, typename C, typename A>
uint32_t kll_sketch<T, C, A>::internal_update() {
allocate_items();
if (levels_[0] == 0) { compress_while_updating(); }
n_++;
is_level_zero_sorted_ = false;
Expand All @@ -213,6 +237,7 @@ void kll_sketch<T, C, A>::merge(FwdSk&& other) {
if (m_ != other.m_) {
throw std::invalid_argument("incompatible M: " + std::to_string(m_) + " and " + std::to_string(other.m_));
}
allocate_items(); // the higher levels are merged into items_ even if other's level zero is empty
if (is_empty()) {
min_item_.emplace(conditional_forward<FwdSk>(*other.min_item_));
max_item_.emplace(conditional_forward<FwdSk>(*other.max_item_));
Expand Down Expand Up @@ -757,7 +782,7 @@ void kll_sketch<T, C, A>::add_empty_top_level_to_completely_full_sketch() {
template<typename T, typename C, typename A>
void kll_sketch<T, C, A>::sort_level_zero() {
if (!is_level_zero_sorted_) {
std::sort(items_ + levels_[0], items_ + levels_[1], comparator_);
std::sort(item_ptr(levels_[0]), item_ptr(levels_[1]), comparator_);
is_level_zero_sorted_ = true;
}
}
Expand All @@ -766,8 +791,8 @@ template<typename T, typename C, typename A>
void kll_sketch<T, C, A>::check_sorting() const {
// not checking level 0
for (uint8_t level = 1; level < num_levels_; ++level) {
const auto from = items_ + levels_[level];
const auto to = items_ + levels_[level + 1];
const auto from = item_ptr(levels_[level]);
const auto to = item_ptr(levels_[level + 1]);
if (!std::is_sorted(from, to, comparator_)) {
throw std::logic_error("levels must be sorted");
}
Expand All @@ -779,8 +804,8 @@ quantiles_sorted_view<T, C, A> kll_sketch<T, C, A>::get_sorted_view() const {
const_cast<kll_sketch*>(this)->sort_level_zero(); // allow this side effect
quantiles_sorted_view<T, C, A> view(get_num_retained(), comparator_, allocator_);
for (uint8_t level = 0; level < num_levels_; ++level) {
const auto from = items_ + levels_[level];
const auto to = items_ + levels_[level + 1]; // exclusive
const auto from = item_ptr(levels_[level]);
const auto to = item_ptr(levels_[level + 1]); // exclusive
view.add(from, to, 1ULL << level);
}
view.convert_to_cummulative();
Expand Down
1 change: 1 addition & 0 deletions kll/test/CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ target_sources(kll_test
PRIVATE
kll_sketch_test.cpp
kll_sketch_custom_type_test.cpp
kll_sketch_allocation_test.cpp
kll_sketch_validation.cpp
kolmogorov_smirnov_test.cpp
)
Expand Down
Loading
Loading