2023-08-15 16:20:26 +02:00
|
|
|
/* SPDX-FileCopyrightText: 2023 Blender Authors
|
2023-05-31 16:19:06 +02:00
|
|
|
*
|
|
|
|
* SPDX-License-Identifier: GPL-2.0-or-later */
|
2020-06-09 10:10:56 +02:00
|
|
|
|
|
|
|
#pragma once
|
|
|
|
|
|
|
|
/** \file
|
|
|
|
* \ingroup bli
|
|
|
|
*
|
|
|
|
* This file contains code that can be shared between different hash table implementations.
|
|
|
|
*/
|
|
|
|
|
2022-02-23 19:02:06 +01:00
|
|
|
#include <algorithm>
|
2020-06-09 10:10:56 +02:00
|
|
|
#include <cmath>
|
|
|
|
|
|
|
|
#include "BLI_allocator.hh"
|
|
|
|
#include "BLI_array.hh"
|
|
|
|
#include "BLI_math_base.h"
|
|
|
|
#include "BLI_memory_utils.hh"
|
|
|
|
#include "BLI_string.h"
|
2020-06-11 11:21:37 +02:00
|
|
|
#include "BLI_string_ref.hh"
|
2020-06-09 10:10:56 +02:00
|
|
|
#include "BLI_utildefines.h"
|
|
|
|
#include "BLI_vector.hh"
|
|
|
|
|
2020-06-09 10:27:24 +02:00
|
|
|
namespace blender {
|
2020-06-09 10:10:56 +02:00
|
|
|
|
|
|
|
/* -------------------------------------------------------------------- */
|
|
|
|
/** \name Constexpr Utility Functions
|
|
|
|
*
|
2020-07-01 05:12:24 +02:00
|
|
|
* Those should eventually be de-duplicated with functions in BLI_math_base.h.
|
2020-06-09 10:10:56 +02:00
|
|
|
* \{ */
|
|
|
|
|
2020-07-20 12:16:20 +02:00
|
|
|
inline constexpr int64_t is_power_of_2_constexpr(const int64_t x)
|
2020-06-09 10:10:56 +02:00
|
|
|
{
|
2020-07-20 12:16:20 +02:00
|
|
|
BLI_assert(x >= 0);
|
|
|
|
return (x & (x - 1)) == 0;
|
2020-06-09 10:10:56 +02:00
|
|
|
}
|
|
|
|
|
2020-07-20 12:16:20 +02:00
|
|
|
inline constexpr int64_t log2_floor_constexpr(const int64_t x)
|
2020-06-09 10:10:56 +02:00
|
|
|
{
|
2020-07-20 12:16:20 +02:00
|
|
|
BLI_assert(x >= 0);
|
|
|
|
return x <= 1 ? 0 : 1 + log2_floor_constexpr(x >> 1);
|
2020-06-09 10:10:56 +02:00
|
|
|
}
|
|
|
|
|
2020-07-20 12:16:20 +02:00
|
|
|
inline constexpr int64_t log2_ceil_constexpr(const int64_t x)
|
2020-06-09 10:10:56 +02:00
|
|
|
{
|
2020-07-20 12:16:20 +02:00
|
|
|
BLI_assert(x >= 0);
|
2022-09-25 17:39:45 +02:00
|
|
|
return (is_power_of_2_constexpr(int(x))) ? log2_floor_constexpr(x) : log2_floor_constexpr(x) + 1;
|
2020-06-09 10:10:56 +02:00
|
|
|
}
|
|
|
|
|
2020-07-20 12:16:20 +02:00
|
|
|
inline constexpr int64_t power_of_2_max_constexpr(const int64_t x)
|
2020-06-09 10:10:56 +02:00
|
|
|
{
|
2020-07-20 12:16:20 +02:00
|
|
|
BLI_assert(x >= 0);
|
|
|
|
return 1ll << log2_ceil_constexpr(x);
|
2020-06-09 10:10:56 +02:00
|
|
|
}
|
|
|
|
|
2020-07-03 14:52:51 +02:00
|
|
|
template<typename IntT> inline constexpr IntT ceil_division(const IntT x, const IntT y)
|
2020-06-09 10:10:56 +02:00
|
|
|
{
|
2020-07-20 12:16:20 +02:00
|
|
|
BLI_assert(x >= 0);
|
|
|
|
BLI_assert(y >= 0);
|
2020-06-09 10:10:56 +02:00
|
|
|
return x / y + ((x % y) != 0);
|
|
|
|
}
|
|
|
|
|
2020-07-03 14:52:51 +02:00
|
|
|
template<typename IntT> inline constexpr IntT floor_division(const IntT x, const IntT y)
|
2020-06-09 10:10:56 +02:00
|
|
|
{
|
2020-07-20 12:16:20 +02:00
|
|
|
BLI_assert(x >= 0);
|
|
|
|
BLI_assert(y >= 0);
|
2020-06-09 10:10:56 +02:00
|
|
|
return x / y;
|
|
|
|
}
|
|
|
|
|
2020-07-20 12:16:20 +02:00
|
|
|
inline constexpr int64_t ceil_division_by_fraction(const int64_t x,
|
|
|
|
const int64_t numerator,
|
|
|
|
const int64_t denominator)
|
2020-06-09 10:10:56 +02:00
|
|
|
{
|
2022-09-25 17:39:45 +02:00
|
|
|
return int64_t(ceil_division(uint64_t(x) * uint64_t(denominator), uint64_t(numerator)));
|
2020-06-09 10:10:56 +02:00
|
|
|
}
|
|
|
|
|
2020-07-20 12:16:20 +02:00
|
|
|
inline constexpr int64_t floor_multiplication_with_fraction(const int64_t x,
|
|
|
|
const int64_t numerator,
|
|
|
|
const int64_t denominator)
|
2020-06-09 10:10:56 +02:00
|
|
|
{
|
2022-09-25 17:39:45 +02:00
|
|
|
return int64_t((uint64_t(x) * uint64_t(numerator) / uint64_t(denominator)));
|
2020-06-09 10:10:56 +02:00
|
|
|
}
|
|
|
|
|
2020-07-20 12:16:20 +02:00
|
|
|
inline constexpr int64_t total_slot_amount_for_usable_slots(
|
|
|
|
const int64_t min_usable_slots,
|
|
|
|
const int64_t max_load_factor_numerator,
|
|
|
|
const int64_t max_load_factor_denominator)
|
2020-06-09 10:10:56 +02:00
|
|
|
{
|
2020-07-20 12:16:20 +02:00
|
|
|
return power_of_2_max_constexpr(ceil_division_by_fraction(
|
2020-06-09 10:10:56 +02:00
|
|
|
min_usable_slots, max_load_factor_numerator, max_load_factor_denominator));
|
|
|
|
}
|
|
|
|
|
|
|
|
/** \} */
|
|
|
|
|
|
|
|
/* -------------------------------------------------------------------- */
|
|
|
|
/** \name Load Factor
|
|
|
|
*
|
|
|
|
* This is an abstraction for a fractional load factor. The hash table using this class is assumed
|
|
|
|
* to use arrays with a size that is a power of two.
|
|
|
|
*
|
|
|
|
* \{ */
|
|
|
|
|
|
|
|
class LoadFactor {
|
|
|
|
private:
|
2020-07-03 14:15:05 +02:00
|
|
|
uint8_t numerator_;
|
|
|
|
uint8_t denominator_;
|
2020-06-09 10:10:56 +02:00
|
|
|
|
|
|
|
public:
|
|
|
|
LoadFactor(uint8_t numerator, uint8_t denominator)
|
2020-07-03 14:15:05 +02:00
|
|
|
: numerator_(numerator), denominator_(denominator)
|
2020-06-09 10:10:56 +02:00
|
|
|
{
|
|
|
|
BLI_assert(numerator > 0);
|
|
|
|
BLI_assert(numerator < denominator);
|
|
|
|
}
|
|
|
|
|
2020-07-20 12:16:20 +02:00
|
|
|
void compute_total_and_usable_slots(int64_t min_total_slots,
|
|
|
|
int64_t min_usable_slots,
|
|
|
|
int64_t *r_total_slots,
|
|
|
|
int64_t *r_usable_slots) const
|
2020-06-09 10:10:56 +02:00
|
|
|
{
|
2022-09-25 17:39:45 +02:00
|
|
|
BLI_assert(is_power_of_2_i(int(min_total_slots)));
|
2020-06-09 10:10:56 +02:00
|
|
|
|
2020-07-20 12:16:20 +02:00
|
|
|
int64_t total_slots = this->compute_total_slots(min_usable_slots, numerator_, denominator_);
|
2020-06-09 10:10:56 +02:00
|
|
|
total_slots = std::max(total_slots, min_total_slots);
|
2020-07-20 12:16:20 +02:00
|
|
|
const int64_t usable_slots = floor_multiplication_with_fraction(
|
2020-07-03 14:15:05 +02:00
|
|
|
total_slots, numerator_, denominator_);
|
2020-06-09 10:10:56 +02:00
|
|
|
BLI_assert(min_usable_slots <= usable_slots);
|
|
|
|
|
|
|
|
*r_total_slots = total_slots;
|
|
|
|
*r_usable_slots = usable_slots;
|
|
|
|
}
|
|
|
|
|
2020-07-20 12:16:20 +02:00
|
|
|
static constexpr int64_t compute_total_slots(int64_t min_usable_slots,
|
|
|
|
uint8_t numerator,
|
|
|
|
uint8_t denominator)
|
2020-06-09 10:10:56 +02:00
|
|
|
{
|
|
|
|
return total_slot_amount_for_usable_slots(min_usable_slots, numerator, denominator);
|
|
|
|
}
|
|
|
|
};
|
|
|
|
|
|
|
|
/** \} */
|
|
|
|
|
|
|
|
/* -------------------------------------------------------------------- */
|
|
|
|
/** \name Intrusive Key Info
|
|
|
|
*
|
|
|
|
* A hash table slot has to maintain state about whether the slot is empty, occupied or removed.
|
|
|
|
* Usually, this state information is stored in its own variable. While it only needs two bits in
|
|
|
|
* theory, in practice often 4 or 8 bytes are used, due to alignment requirements.
|
|
|
|
*
|
|
|
|
* One solution to deal with this problem is to embed the state information in the key. That means,
|
|
|
|
* two values of the key type are selected to indicate whether the slot is empty or removed.
|
|
|
|
*
|
|
|
|
* The classes below tell a slot implementation which special key values it can use. They can be
|
2020-06-25 15:13:02 +02:00
|
|
|
* used as #KeyInfo in slot types like #IntrusiveSetSlot and #IntrusiveMapSlot.
|
2020-06-09 10:10:56 +02:00
|
|
|
*
|
2020-06-25 15:13:02 +02:00
|
|
|
* A #KeyInfo type has to implement a couple of static methods that are descried in
|
|
|
|
* #TemplatedKeyInfo.
|
2020-06-09 10:10:56 +02:00
|
|
|
*
|
|
|
|
* \{ */
|
|
|
|
|
|
|
|
/**
|
|
|
|
* The template arguments EmptyValue and RemovedValue define which special are used. This can be
|
|
|
|
* used when a hash table has integer keys and there are two specific integers that will never be
|
|
|
|
* used as keys.
|
|
|
|
*/
|
|
|
|
template<typename Key, Key EmptyValue, Key RemovedValue> struct TemplatedKeyInfo {
|
|
|
|
/**
|
|
|
|
* Get the value that indicates that the slot is empty. This is used to indicate new slots.
|
|
|
|
*/
|
|
|
|
static Key get_empty()
|
|
|
|
{
|
|
|
|
return EmptyValue;
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Modify the given key so that it represents a removed slot.
|
|
|
|
*/
|
|
|
|
static void remove(Key &key)
|
|
|
|
{
|
|
|
|
key = RemovedValue;
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Return true, when the given key indicates that the slot is empty.
|
|
|
|
*/
|
|
|
|
static bool is_empty(const Key &key)
|
|
|
|
{
|
|
|
|
return key == EmptyValue;
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Return true, when the given key indicates that the slot is removed.
|
|
|
|
*/
|
|
|
|
static bool is_removed(const Key &key)
|
|
|
|
{
|
|
|
|
return key == RemovedValue;
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Return true, when the key is valid, i.e. it can be contained in an occupied slot.
|
|
|
|
*/
|
|
|
|
static bool is_not_empty_or_removed(const Key &key)
|
|
|
|
{
|
|
|
|
return key != EmptyValue && key != RemovedValue;
|
|
|
|
}
|
|
|
|
};
|
|
|
|
|
|
|
|
/**
|
2022-06-09 02:16:26 +02:00
|
|
|
* `0xffff...ffff` indicates an empty slot.
|
|
|
|
* `0xffff...fffe` indicates a removed slot.
|
2020-06-09 10:10:56 +02:00
|
|
|
*
|
|
|
|
* Those specific values are used, because with them a single comparison is enough to check whether
|
2022-06-09 02:16:26 +02:00
|
|
|
* a slot is occupied. The keys `0x0000...0000` and `0x0000...0001` also satisfy this constraint.
|
2020-06-09 10:10:56 +02:00
|
|
|
* However, nullptr is much more likely to be used as valid key.
|
|
|
|
*/
|
|
|
|
template<typename Pointer> struct PointerKeyInfo {
|
|
|
|
static Pointer get_empty()
|
|
|
|
{
|
|
|
|
return (Pointer)UINTPTR_MAX;
|
|
|
|
}
|
|
|
|
|
|
|
|
static void remove(Pointer &pointer)
|
|
|
|
{
|
|
|
|
pointer = (Pointer)(UINTPTR_MAX - 1);
|
|
|
|
}
|
|
|
|
|
|
|
|
static bool is_empty(Pointer pointer)
|
|
|
|
{
|
2022-09-26 09:38:25 +02:00
|
|
|
return uintptr_t(pointer) == UINTPTR_MAX;
|
2020-06-09 10:10:56 +02:00
|
|
|
}
|
|
|
|
|
|
|
|
static bool is_removed(Pointer pointer)
|
|
|
|
{
|
2022-09-26 09:38:25 +02:00
|
|
|
return uintptr_t(pointer) == UINTPTR_MAX - 1;
|
2020-06-09 10:10:56 +02:00
|
|
|
}
|
|
|
|
|
|
|
|
static bool is_not_empty_or_removed(Pointer pointer)
|
|
|
|
{
|
2022-09-26 09:38:25 +02:00
|
|
|
return uintptr_t(pointer) < UINTPTR_MAX - 1;
|
2020-06-09 10:10:56 +02:00
|
|
|
}
|
|
|
|
};
|
|
|
|
|
|
|
|
/** \} */
|
|
|
|
|
|
|
|
/* -------------------------------------------------------------------- */
|
|
|
|
/** \name Hash Table Stats
|
|
|
|
*
|
|
|
|
* A utility class that makes it easier for hash table implementations to provide statistics to the
|
|
|
|
* developer. These statistics can be helpful when trying to figure out why a hash table is slow.
|
|
|
|
*
|
|
|
|
* To use this utility, a hash table has to implement various methods, that are mentioned below.
|
|
|
|
*
|
|
|
|
* \{ */
|
|
|
|
|
|
|
|
class HashTableStats {
|
|
|
|
private:
|
2020-07-20 12:16:20 +02:00
|
|
|
Vector<int64_t> keys_by_collision_count_;
|
|
|
|
int64_t total_collisions_;
|
2020-07-03 14:15:05 +02:00
|
|
|
float average_collisions_;
|
2020-07-20 12:16:20 +02:00
|
|
|
int64_t size_;
|
|
|
|
int64_t capacity_;
|
|
|
|
int64_t removed_amount_;
|
2020-07-03 14:15:05 +02:00
|
|
|
float load_factor_;
|
|
|
|
float removed_load_factor_;
|
2020-07-20 12:16:20 +02:00
|
|
|
int64_t size_per_element_;
|
|
|
|
int64_t size_in_bytes_;
|
2020-07-03 14:15:05 +02:00
|
|
|
const void *address_;
|
2020-06-09 10:10:56 +02:00
|
|
|
|
|
|
|
public:
|
|
|
|
/**
|
|
|
|
* Requires that the hash table has the following methods:
|
2020-07-20 12:16:20 +02:00
|
|
|
* - count_collisions(key) -> int64_t
|
|
|
|
* - size() -> int64_t
|
|
|
|
* - capacity() -> int64_t
|
|
|
|
* - removed_amount() -> int64_t
|
|
|
|
* - size_per_element() -> int64_t
|
|
|
|
* - size_in_bytes() -> int64_t
|
2020-06-09 10:10:56 +02:00
|
|
|
*/
|
|
|
|
template<typename HashTable, typename Keys>
|
|
|
|
HashTableStats(const HashTable &hash_table, const Keys &keys)
|
|
|
|
{
|
2020-07-03 14:15:05 +02:00
|
|
|
total_collisions_ = 0;
|
|
|
|
size_ = hash_table.size();
|
|
|
|
capacity_ = hash_table.capacity();
|
|
|
|
removed_amount_ = hash_table.removed_amount();
|
|
|
|
size_per_element_ = hash_table.size_per_element();
|
|
|
|
size_in_bytes_ = hash_table.size_in_bytes();
|
2020-08-07 18:24:59 +02:00
|
|
|
address_ = static_cast<const void *>(&hash_table);
|
2020-06-09 10:10:56 +02:00
|
|
|
|
|
|
|
for (const auto &key : keys) {
|
2020-07-20 12:16:20 +02:00
|
|
|
int64_t collisions = hash_table.count_collisions(key);
|
2020-07-03 14:15:05 +02:00
|
|
|
if (keys_by_collision_count_.size() <= collisions) {
|
|
|
|
keys_by_collision_count_.append_n_times(0,
|
|
|
|
collisions - keys_by_collision_count_.size() + 1);
|
2020-06-09 10:10:56 +02:00
|
|
|
}
|
2020-07-03 14:15:05 +02:00
|
|
|
keys_by_collision_count_[collisions]++;
|
|
|
|
total_collisions_ += collisions;
|
2020-06-09 10:10:56 +02:00
|
|
|
}
|
|
|
|
|
2020-07-03 14:15:05 +02:00
|
|
|
average_collisions_ = (size_ == 0) ? 0 : (float)total_collisions_ / (float)size_;
|
|
|
|
load_factor_ = (float)size_ / (float)capacity_;
|
|
|
|
removed_load_factor_ = (float)removed_amount_ / (float)capacity_;
|
2020-06-09 10:10:56 +02:00
|
|
|
}
|
|
|
|
|
Cleanup: fewer iostreams related includes from BLI/BKE headers
Including <iostream> or similar headers is quite expensive, since it
also pulls in things like <locale> and so on. In many BLI headers,
iostreams are only used to implement some sort of "debug print",
or an operator<< for ostream.
Change some of the commonly used places to instead include <iosfwd>,
which is the standard way of forward-declaring iostreams related
classes, and move the actual debug-print / operator<< implementations
into .cc files.
This is not done for templated classes though (it would be possible
to provide explicit operator<< instantiations somewhere in the
source file, but that would lead to hard-to-figure-out linker error
whenever someone would add a different template type). There, where
possible, I changed from full <iostream> include to only the needed
<ostream> part.
For Span<T>, I just removed print_as_lines since it's not used by
anything. It could be moved into a .cc file using a similar approach
as above if needed.
Doing full blender build changes include counts this way:
- <iostream> 1986 -> 978
- <sstream> 2880 -> 925
It does not affect the total build time much though, mostly because
towards the end of it there's just several CPU cores finishing
compiling OpenVDB related source files.
Pull Request: https://projects.blender.org/blender/blender/pulls/111046
2023-08-11 11:27:56 +02:00
|
|
|
void print(StringRef name = "") const;
|
2020-06-09 10:10:56 +02:00
|
|
|
};
|
|
|
|
|
|
|
|
/** \} */
|
|
|
|
|
|
|
|
/**
|
|
|
|
* This struct provides an equality operator that returns true for all objects that compare equal
|
|
|
|
* when one would use the `==` operator. This is different from std::equal_to<T>, because that
|
|
|
|
* requires the parameters to be of type T. Our hash tables support lookups using other types
|
|
|
|
* without conversion, therefore DefaultEquality needs to be more generic.
|
|
|
|
*/
|
2022-11-21 12:02:10 +01:00
|
|
|
template<typename T> struct DefaultEquality {
|
2020-06-09 10:10:56 +02:00
|
|
|
template<typename T1, typename T2> bool operator()(const T1 &a, const T2 &b) const
|
|
|
|
{
|
|
|
|
return a == b;
|
|
|
|
}
|
|
|
|
};
|
|
|
|
|
2022-11-21 12:02:10 +01:00
|
|
|
/**
|
|
|
|
* Support comparing different kinds of raw and smart pointers.
|
|
|
|
*/
|
|
|
|
struct PointerComparison {
|
|
|
|
template<typename T1, typename T2> bool operator()(const T1 &a, const T2 &b) const
|
|
|
|
{
|
|
|
|
return &*a == &*b;
|
|
|
|
}
|
|
|
|
};
|
|
|
|
|
|
|
|
template<typename T> struct DefaultEquality<std::unique_ptr<T>> : public PointerComparison {
|
|
|
|
};
|
|
|
|
template<typename T> struct DefaultEquality<std::shared_ptr<T>> : public PointerComparison {
|
|
|
|
};
|
|
|
|
|
2022-12-29 14:59:48 +01:00
|
|
|
struct SequenceComparison {
|
|
|
|
template<typename T1, typename T2> bool operator()(const T1 &a, const T2 &b) const
|
|
|
|
{
|
|
|
|
const auto a_begin = a.begin();
|
|
|
|
const auto a_end = a.end();
|
|
|
|
const auto b_begin = b.begin();
|
|
|
|
const auto b_end = b.end();
|
|
|
|
if (a_end - a_begin != b_end - b_begin) {
|
|
|
|
return false;
|
|
|
|
}
|
|
|
|
return std::equal(a_begin, a_end, b_begin);
|
|
|
|
}
|
|
|
|
};
|
|
|
|
|
|
|
|
template<typename T, int64_t InlineBufferCapacity, typename Allocator>
|
|
|
|
struct DefaultEquality<Vector<T, InlineBufferCapacity, Allocator>> : public SequenceComparison {
|
|
|
|
};
|
|
|
|
|
2020-06-09 10:27:24 +02:00
|
|
|
} // namespace blender
|