2020-03-30 00:31:24 +00:00
|
|
|
#ifndef BLOOM_H
|
|
|
|
#define BLOOM_H
|
|
|
|
|
2020-03-30 00:31:26 +00:00
|
|
|
struct commit;
|
|
|
|
struct repository;
|
|
|
|
|
bloom.c: introduce core Bloom filter constructs
Introduce the constructs for Bloom filters, Bloom filter keys
and Bloom filter settings.
For details on what Bloom filters are and how they work, refer
to Dr. Derrick Stolee's blog post [1]. It provides a concise
explanation of the adoption of Bloom filters as described in
[2] and [3].
Implementation specifics:
1. We currently use 7 and 10 for the number of hashes and the
size of each entry respectively. They served as great starting
values, the mathematical details behind this choice are
described in [1] and [4]. The implementation, while not
completely open to it at the moment, is flexible enough to allow
for tweaking these settings in the future.
Note: The performance gains we have observed with these values
are significant enough that we did not need to tweak these
settings. The performance numbers are included in the cover letter
of this series and in the commit message of the subsequent commit
where we use Bloom filters to speed up `git log -- path`.
2. As described in [1] and [3], we do not need 7 independent hashing
functions. We use the Murmur3 hashing scheme, seed it twice and
then combine those to procure an arbitrary number of hash values.
3. The filters will be sized according to the number of changes in
each commit, in multiples of 8 bit words.
[1] Derrick Stolee
"Supercharging the Git Commit Graph IV: Bloom Filters"
https://devblogs.microsoft.com/devops/super-charging-the-git-commit-graph-iv-Bloom-filters/
[2] Flavio Bonomi, Michael Mitzenmacher, Rina Panigrahy, Sushil Singh, George Varghese
"An Improved Construction for Counting Bloom Filters"
http://theory.stanford.edu/~rinap/papers/esa2006b.pdf
https://doi.org/10.1007/11841036_61
[3] Peter C. Dillinger and Panagiotis Manolios
"Bloom Filters in Probabilistic Verification"
http://www.ccs.neu.edu/home/pete/pub/Bloom-filters-verification.pdf
https://doi.org/10.1007/978-3-540-30494-4_26
[4] Thomas Mueller Graf, Daniel Lemire
"Xor Filters: Faster and Smaller Than Bloom and Cuckoo Filters"
https://arxiv.org/abs/1912.08258
Helped-by: Derrick Stolee <dstolee@microsoft.com>
Reviewed-by: Jakub Narębski <jnareb@gmail.com>
Signed-off-by: Garima Singh <garima.singh@microsoft.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-03-30 00:31:25 +00:00
|
|
|
struct bloom_filter_settings {
|
|
|
|
/*
|
|
|
|
* The version of the hashing technique being used.
|
|
|
|
* We currently only support version = 1 which is
|
|
|
|
* the seeded murmur3 hashing technique implemented
|
|
|
|
* in bloom.c.
|
|
|
|
*/
|
|
|
|
uint32_t hash_version;
|
|
|
|
|
|
|
|
/*
|
|
|
|
* The number of times a path is hashed, i.e. the
|
|
|
|
* number of bit positions tht cumulatively
|
|
|
|
* determine whether a path is present in the
|
|
|
|
* Bloom filter.
|
|
|
|
*/
|
|
|
|
uint32_t num_hashes;
|
|
|
|
|
|
|
|
/*
|
|
|
|
* The minimum number of bits per entry in the Bloom
|
|
|
|
* filter. If the filter contains 'n' entries, then
|
|
|
|
* filter size is the minimum number of 8-bit words
|
|
|
|
* that contain n*b bits.
|
|
|
|
*/
|
|
|
|
uint32_t bits_per_entry;
|
|
|
|
};
|
|
|
|
|
|
|
|
#define DEFAULT_BLOOM_FILTER_SETTINGS { 1, 7, 10 }
|
|
|
|
#define BITS_PER_WORD 8
|
|
|
|
|
|
|
|
/*
|
|
|
|
* A bloom_filter struct represents a data segment to
|
|
|
|
* use when testing hash values. The 'len' member
|
|
|
|
* dictates how many entries are stored in
|
|
|
|
* 'data'.
|
|
|
|
*/
|
|
|
|
struct bloom_filter {
|
|
|
|
unsigned char *data;
|
|
|
|
size_t len;
|
|
|
|
};
|
|
|
|
|
|
|
|
/*
|
|
|
|
* A bloom_key represents the k hash values for a
|
|
|
|
* given string. These can be precomputed and
|
|
|
|
* stored in a bloom_key for re-use when testing
|
|
|
|
* against a bloom_filter. The number of hashes is
|
|
|
|
* given by the Bloom filter settings and is the same
|
|
|
|
* for all Bloom filters and keys interacting with
|
|
|
|
* the loaded version of the commit graph file and
|
|
|
|
* the Bloom data chunks.
|
|
|
|
*/
|
|
|
|
struct bloom_key {
|
|
|
|
uint32_t *hashes;
|
|
|
|
};
|
|
|
|
|
2020-03-30 00:31:24 +00:00
|
|
|
/*
|
|
|
|
* Calculate the murmur3 32-bit hash value for the given data
|
|
|
|
* using the given seed.
|
|
|
|
* Produces a uniformly distributed hash value.
|
|
|
|
* Not considered to be cryptographically secure.
|
|
|
|
* Implemented as described in https://en.wikipedia.org/wiki/MurmurHash#Algorithm
|
|
|
|
*/
|
|
|
|
uint32_t murmur3_seeded(uint32_t seed, const char *data, size_t len);
|
|
|
|
|
bloom.c: introduce core Bloom filter constructs
Introduce the constructs for Bloom filters, Bloom filter keys
and Bloom filter settings.
For details on what Bloom filters are and how they work, refer
to Dr. Derrick Stolee's blog post [1]. It provides a concise
explanation of the adoption of Bloom filters as described in
[2] and [3].
Implementation specifics:
1. We currently use 7 and 10 for the number of hashes and the
size of each entry respectively. They served as great starting
values, the mathematical details behind this choice are
described in [1] and [4]. The implementation, while not
completely open to it at the moment, is flexible enough to allow
for tweaking these settings in the future.
Note: The performance gains we have observed with these values
are significant enough that we did not need to tweak these
settings. The performance numbers are included in the cover letter
of this series and in the commit message of the subsequent commit
where we use Bloom filters to speed up `git log -- path`.
2. As described in [1] and [3], we do not need 7 independent hashing
functions. We use the Murmur3 hashing scheme, seed it twice and
then combine those to procure an arbitrary number of hash values.
3. The filters will be sized according to the number of changes in
each commit, in multiples of 8 bit words.
[1] Derrick Stolee
"Supercharging the Git Commit Graph IV: Bloom Filters"
https://devblogs.microsoft.com/devops/super-charging-the-git-commit-graph-iv-Bloom-filters/
[2] Flavio Bonomi, Michael Mitzenmacher, Rina Panigrahy, Sushil Singh, George Varghese
"An Improved Construction for Counting Bloom Filters"
http://theory.stanford.edu/~rinap/papers/esa2006b.pdf
https://doi.org/10.1007/11841036_61
[3] Peter C. Dillinger and Panagiotis Manolios
"Bloom Filters in Probabilistic Verification"
http://www.ccs.neu.edu/home/pete/pub/Bloom-filters-verification.pdf
https://doi.org/10.1007/978-3-540-30494-4_26
[4] Thomas Mueller Graf, Daniel Lemire
"Xor Filters: Faster and Smaller Than Bloom and Cuckoo Filters"
https://arxiv.org/abs/1912.08258
Helped-by: Derrick Stolee <dstolee@microsoft.com>
Reviewed-by: Jakub Narębski <jnareb@gmail.com>
Signed-off-by: Garima Singh <garima.singh@microsoft.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2020-03-30 00:31:25 +00:00
|
|
|
void fill_bloom_key(const char *data,
|
|
|
|
size_t len,
|
|
|
|
struct bloom_key *key,
|
|
|
|
const struct bloom_filter_settings *settings);
|
|
|
|
|
|
|
|
void add_key_to_filter(const struct bloom_key *key,
|
|
|
|
struct bloom_filter *filter,
|
|
|
|
const struct bloom_filter_settings *settings);
|
|
|
|
|
2020-03-30 00:31:26 +00:00
|
|
|
void init_bloom_filters(void);
|
|
|
|
|
|
|
|
struct bloom_filter *get_bloom_filter(struct repository *r,
|
|
|
|
struct commit *c);
|
|
|
|
|
2020-03-30 00:31:24 +00:00
|
|
|
#endif
|