23
23
//!
24
24
//! This module provides the following key components:
25
25
//!
26
- //! - `CuckooTableConfig`: Configuration for the cuckoo table, including the number of hash functions,
27
- //! maximum eviction count, maximum serialized bucket size, and bucket count configuration.
28
- //! - `CuckooTable`: The main data structure implementing the cuckoo hash table, supporting insertion,
29
- //! lookup, and expansion of the table.
26
+ //! - `CuckooTableConfig`: Configuration for the cuckoo table, including the number of hash
27
+ //! functions, maximum eviction count, maximum serialized bucket size, and bucket count
28
+ //! configuration.
29
+ //! - `CuckooTable`: The main data structure implementing the cuckoo hash table, supporting
30
+ //! insertion, lookup, and expansion of the table.
30
31
//! - `CuckooBucket`: Represents a single bucket in the cuckoo table, storing a list of entries.
31
- //! - `CuckooBucketEntry`: Represents a single entry in a cuckoo bucket, consisting of a keyword and a value.
32
- //! - `CuckooTableInformation`: Provides a summary of the cuckoo table, including entry count, bucket count,
33
- //! empty bucket count, and load factor.
32
+ //! - `CuckooBucketEntry`: Represents a single entry in a cuckoo bucket, consisting of a keyword and
33
+ //! a value.
34
+ //! - `CuckooTableInformation`: Provides a summary of the cuckoo table, including entry count,
35
+ //! bucket count, empty bucket count, and load factor.
34
36
//!
35
- //! The implementation of hash table entries, `CuckooBucketEntry`, is taken from the `hash_bucket` module.
37
+ //! The implementation of hash table entries, `CuckooBucketEntry`, is taken from the `hash_bucket`
38
+ //! module.
39
+
40
+ use std:: fmt;
36
41
37
- use crate :: homomorphic_encryption:: scalar:: dividing_ceil;
38
- use crate :: private_information_retrieval:: error:: PirError ;
39
- use crate :: private_information_retrieval:: hash_bucket:: { HashBucket , HashKeyword } ;
40
- use crate :: private_information_retrieval:: keyword_database:: { Keyword , KeywordValue } ;
41
42
use eyre:: Result ;
42
43
use rand:: seq:: SliceRandom ;
43
44
use rand_core:: RngCore ;
44
- use std:: fmt;
45
45
use thiserror:: Error ;
46
46
47
+ use crate :: {
48
+ homomorphic_encryption:: scalar:: dividing_ceil,
49
+ private_information_retrieval:: {
50
+ error:: PirError ,
51
+ hash_bucket:: { HashBucket , HashKeyword } ,
52
+ keyword_database:: { Keyword , KeywordValue } ,
53
+ } ,
54
+ } ;
55
+
47
56
/// Cuckoo table config errors.
48
57
#[ derive( Debug , Clone , Error , PartialEq ) ]
49
58
pub enum CuckooTableConfigError {
50
59
/// Invalid hash function count. Must be greater than 0.
51
60
#[ error( "Invalid hash function count" ) ]
52
61
InvalidHashFunctionCount ,
53
62
54
- /// Invalid maximum serialized bucket size. Must be greater than zero and less than `HashBucket::serialized_size_with_value_size(0)`.
63
+ /// Invalid maximum serialized bucket size. Must be greater than zero and less than
64
+ /// `HashBucket::serialized_size_with_value_size(0)`.
55
65
#[ error( "Invalid maximum serialized bucket size" ) ]
56
66
InvalidMaxSerializedBucketSize ,
57
67
@@ -73,11 +83,12 @@ pub enum CuckooTableConfigError {
73
83
pub enum BucketCountConfig {
74
84
/// Allow increasing the number of buckets.
75
85
///
76
- /// The load factor measures what fraction of the cuckoo table's capacity is filled with data, as measured by
77
- /// serialization size. The target load factor is used to reserve capacity in the cuckoo table at initialization
78
- /// and expansion as entries are inserted.
86
+ /// The load factor measures what fraction of the cuckoo table's capacity is filled with data,
87
+ /// as measured by serialization size. The target load factor is used to reserve capacity
88
+ /// in the cuckoo table at initialization and expansion as entries are inserted.
79
89
AllowExpansion {
80
- /// Multiplicative factor by which to increase the number of buckets during expansion. Must be > 1.0.
90
+ /// Multiplicative factor by which to increase the number of buckets during expansion. Must
91
+ /// be > 1.0.
81
92
expansion_factor : f64 ,
82
93
/// Fraction of the cuckoo table's capacity to fill with data. Must be in `[0.0, 1.0]`.
83
94
target_load_factor : f64 ,
@@ -118,7 +129,6 @@ impl CuckooTableConfig {
118
129
/// - `max_eviction_count`: Maximum number of evictions to perform when inserting a new entry.
119
130
/// - `max_serialized_bucket_size`: Maximum size of a serialized bucket, in bytes.
120
131
/// - `bucket_count`: Number of buckets in the cuckoo table.
121
- ///
122
132
pub fn new (
123
133
hash_function_count : usize ,
124
134
max_eviction_count : usize ,
@@ -263,7 +273,6 @@ impl CuckooBucket {
263
273
///
264
274
/// - `value`: The value to insert.
265
275
/// - `config`: The cuckoo table configuration.
266
- ///
267
276
pub fn can_insert ( & self , value : & KeywordValue , config : & CuckooTableConfig ) -> bool {
268
277
if self . slots . len ( ) >= HashBucket :: MAX_SLOT_COUNT {
269
278
return false ;
@@ -279,7 +288,6 @@ impl CuckooBucket {
279
288
///
280
289
/// - `new_value`: The value to insert.
281
290
/// - `config`: The cuckoo table configuration.
282
- ///
283
291
pub fn swap_indices ( & self , new_value : & Vec < u8 > , config : & CuckooTableConfig ) -> Vec < usize > {
284
292
let current_values: Vec < & Vec < u8 > > = self . slots . iter ( ) . map ( |entry| & entry. value ) . collect ( ) ;
285
293
// Loop over prefixes that include `newValue` but omit a single existing value
@@ -327,8 +335,8 @@ impl EvictIndex {
327
335
}
328
336
}
329
337
330
- /// A Cuckoo table is a data structure that stores a set of keyword-value pairs, using cuckoo hashing to resolve
331
- /// conflicts.
338
+ /// A Cuckoo table is a data structure that stores a set of keyword-value pairs, using cuckoo
339
+ /// hashing to resolve conflicts.
332
340
pub struct CuckooTable {
333
341
/// The configuration for the cuckoo table.
334
342
pub config : CuckooTableConfig ,
@@ -527,7 +535,6 @@ impl CuckooTable {
527
535
/// - `hash_index`: The index of the hash, provided by `HashKeyword::hash_indices`.
528
536
///
529
537
/// # Returns
530
- ///
531
538
pub fn index ( & self , table_index : usize , hash_index : usize ) -> usize {
532
539
if self . table_count ( ) == 1 {
533
540
hash_index
@@ -538,8 +545,9 @@ impl CuckooTable {
538
545
539
546
/// Expands the cuckoo table.
540
547
///
541
- /// Expansion is only allowed if the configuration allows it. If allowed, the number of buckets is increased by the
542
- /// expansion factor. Old entries are rehashed and inserted into the new buckets.
548
+ /// Expansion is only allowed if the configuration allows it. If allowed, the number of buckets
549
+ /// is increased by the expansion factor. Old entries are rehashed and inserted into the new
550
+ /// buckets.
543
551
///
544
552
/// # Errors
545
553
///
@@ -628,12 +636,13 @@ impl CuckooTable {
628
636
629
637
#[ cfg( test) ]
630
638
mod tests {
631
- use crate :: private_information_retrieval:: cuckoo_table:: * ;
632
- use crate :: private_information_retrieval:: hash_bucket:: HashKeyword ;
633
- use crate :: private_information_retrieval:: pir_test_utils:: get_test_table;
634
639
use rand:: rngs:: StdRng ;
635
640
use rand_core:: SeedableRng ;
636
641
642
+ use crate :: private_information_retrieval:: {
643
+ cuckoo_table:: * , hash_bucket:: HashKeyword , pir_test_utils:: get_test_table,
644
+ } ;
645
+
637
646
fn get_test_cuckoo_table_config ( max_serialized_bucket_size : usize ) -> CuckooTableConfig {
638
647
CuckooTableConfig {
639
648
hash_function_count : 2 ,
0 commit comments