From 2fd9da973bf41ef8282c94fc44803c2ed743f663 Mon Sep 17 00:00:00 2001 From: "M.V. Hutz" Date: Sat, 4 Apr 2026 12:22:42 +0200 Subject: [PATCH 1/4] refactor: bucket -> table, Table -> HashTable --- bucket.go | 103 ------------------- hash_table.go | 237 +++++++++++++++++++++++++++++++++++++++++++ table.go | 274 +++++++++++++------------------------------------- 3 files changed, 307 insertions(+), 307 deletions(-) delete mode 100644 bucket.go create mode 100644 hash_table.go diff --git a/bucket.go b/bucket.go deleted file mode 100644 index 6a4171c..0000000 --- a/bucket.go +++ /dev/null @@ -1,103 +0,0 @@ -package cuckoo - -type entry[K, V any] struct { - key K - value V -} - -type slot[K, V any] struct { - entry[K, V] - occupied bool -} - -type bucket[K, V any] struct { - hash Hash[K] - slots []slot[K, V] - capacity, size uint64 - compare EqualFunc[K] -} - -// location determines where in the bucket a certain key would be placed. If the -// capacity is 0, this will panic. -func (b bucket[K, V]) location(key K) uint64 { - return b.hash(key) % b.capacity -} - -func (b bucket[K, V]) get(key K) (value V, found bool) { - if b.capacity == 0 { - return - } - - slot := b.slots[b.location(key)] - return slot.value, slot.occupied && b.compare(slot.key, key) -} - -func (b *bucket[K, V]) drop(key K) (occupied bool) { - if b.capacity == 0 { - return - } - - slot := &b.slots[b.location(key)] - - if slot.occupied && b.compare(slot.key, key) { - slot.occupied = false - b.size-- - return true - } - - return false -} - -func (b *bucket[K, V]) resize(capacity uint64) { - b.slots = make([]slot[K, V], capacity) - b.capacity = capacity - b.size = 0 -} - -func (b bucket[K, V]) update(key K, value V) (updated bool) { - if b.capacity == 0 { - return - } - - slot := &b.slots[b.location(key)] - - if slot.occupied && b.compare(slot.key, key) { - slot.value = value - return true - } - - return false -} - -func (b *bucket[K, V]) evict(insertion entry[K, V]) (evicted entry[K, V], eviction bool) { - if b.capacity == 0 { - return insertion, true - } - - slot := &b.slots[b.location(insertion.key)] - - if !slot.occupied { - slot.entry = insertion - slot.occupied = true - b.size++ - return - } - - if b.compare(slot.key, insertion.key) { - slot.value = insertion.value - return - } - - insertion, slot.entry = slot.entry, insertion - return insertion, true -} - -func newBucket[K, V any](capacity uint64, hash Hash[K], compare EqualFunc[K]) bucket[K, V] { - return bucket[K, V]{ - hash: hash, - capacity: capacity, - compare: compare, - size: 0, - slots: make([]slot[K, V], capacity), - } -} diff --git a/hash_table.go b/hash_table.go new file mode 100644 index 0000000..9e037ac --- /dev/null +++ b/hash_table.go @@ -0,0 +1,237 @@ +package cuckoo + +import ( + "fmt" + "iter" + "math/bits" + "strings" +) + +// A HashTable is hash table that uses cuckoo hashing to resolve collision. Create +// one with [NewTable]. Or if you want more granularity, use [NewTableBy] or +// [NewCustomTable]. +type HashTable[K, V any] struct { + tableA, tableB table[K, V] + growthFactor uint64 + minLoadFactor float64 +} + +// TotalCapacity returns the number of slots allocated for the [HashTable]. To get the +// number of slots filled, look at [HashTable.Size]. +func (t *HashTable[K, V]) TotalCapacity() uint64 { + return t.tableA.capacity + t.tableB.capacity +} + +// Size returns how many slots are filled in the [HashTable]. +func (t *HashTable[K, V]) Size() int { + return int(t.tableA.size + t.tableB.size) +} + +func log2(n uint64) (m int) { + return max(0, bits.Len64(n)-1) +} + +func (t *HashTable[K, V]) maxEvictions() int { + return 3 * log2(t.TotalCapacity()) +} + +func (t *HashTable[K, V]) load() float64 { + // When there are no slots in the table, we still treat the load as 100%. + // Every slot in the table is full. + if t.TotalCapacity() == 0 { + return 1.0 + } + + return float64(t.Size()) / float64(t.TotalCapacity()) +} + +// resize clears all buckets, changes the sizes of them to a specific capacity, +// and fills them back up again. It is a helper function for [HashTable.grow] and +// [HashTable.shrink]; use them instead. +func (t *HashTable[K, V]) resize(capacity uint64) error { + entries := make([]entry[K, V], 0, t.Size()) + for k, v := range t.Entries() { + entries = append(entries, entry[K, V]{k, v}) + } + + t.tableA.resize(capacity) + t.tableB.resize(capacity) + + for _, entry := range entries { + if err := t.Put(entry.key, entry.value); err != nil { + return err + } + } + + return nil +} + +// grow increases the table's capacity by the [HashTable.growthFactor]. If the +// capacity is 0, it increases it to 1. +func (t *HashTable[K, V]) grow() error { + var newCapacity uint64 + + if t.TotalCapacity() == 0 { + newCapacity = 1 + } else { + newCapacity = t.tableA.capacity * t.growthFactor + } + + return t.resize(newCapacity) +} + +// shrink reduces the table's capacity by the [HashTable.growthFactor]. It may +// reduce it down to 0. +func (t *HashTable[K, V]) shrink() error { + return t.resize(t.tableA.capacity / t.growthFactor) +} + +// Get fetches the value for a key in the [HashTable]. Returns an error if no value +// is found. +func (t *HashTable[K, V]) Get(key K) (value V, err error) { + if item, ok := t.tableA.get(key); ok { + return item, nil + } + + if item, ok := t.tableB.get(key); ok { + return item, nil + } + + return value, fmt.Errorf("key '%v' not found", key) +} + +// Has returns true if a key has a value in the table. +func (t *HashTable[K, V]) Has(key K) (exists bool) { + _, err := t.Get(key) + return err == nil +} + +// Put sets the value for a key. Returns error if its value cannot be set. +func (t *HashTable[K, V]) Put(key K, value V) (err error) { + if t.tableA.update(key, value) { + return nil + } + + if t.tableB.update(key, value) { + return nil + } + + entry, eviction := entry[K, V]{key, value}, false + for range t.maxEvictions() { + if entry, eviction = t.tableA.evict(entry); !eviction { + return nil + } + + if entry, eviction = t.tableB.evict(entry); !eviction { + return nil + } + } + + if t.load() < t.minLoadFactor { + return fmt.Errorf("bad hash: resize on load %d/%d = %f", t.Size(), t.TotalCapacity(), t.load()) + } + + if err := t.grow(); err != nil { + return err + } + + return t.Put(entry.key, entry.value) +} + +// Drop removes a value for a key in the table. Returns an error if its value +// cannot be removed. +func (t *HashTable[K, V]) Drop(key K) (err error) { + t.tableA.drop(key) + t.tableB.drop(key) + + if t.load() < t.minLoadFactor { + return t.shrink() + } + + return nil +} + +// Entries returns an unordered sequence of all key-value pairs in the table. +func (t *HashTable[K, V]) Entries() iter.Seq2[K, V] { + return func(yield func(K, V) bool) { + for _, slot := range t.tableA.slots { + if slot.occupied { + if !yield(slot.key, slot.value) { + return + } + } + } + + for _, slot := range t.tableB.slots { + if slot.occupied { + if !yield(slot.key, slot.value) { + return + } + } + } + } +} + +// String returns the entries of the table as a string in the format: +// "table[k1:v1 h2:v2 ...]". +func (t *HashTable[K, V]) String() string { + var sb strings.Builder + sb.WriteString("table[") + + first := true + for k, v := range t.Entries() { + if !first { + sb.WriteString(" ") + } + + fmt.Fprintf(&sb, "%v:%v", k, v) + first = false + } + + sb.WriteString("]") + return sb.String() +} + +// NewCustomTable creates a [HashTable] with custom [Hash] and [EqualFunc] +// functions, along with any [Option] the user provides. +func NewCustomTable[K, V any](hashA, hashB Hash[K], compare EqualFunc[K], options ...Option) *HashTable[K, V] { + settings := &settings{ + growthFactor: DefaultGrowthFactor, + bucketSize: DefaultCapacity, + minLoadFactor: defaultMinimumLoad, + } + + for _, option := range options { + option(settings) + } + + return &HashTable[K, V]{ + growthFactor: settings.growthFactor, + minLoadFactor: settings.minLoadFactor, + tableA: newTable[K, V](settings.bucketSize, hashA, compare), + tableB: newTable[K, V](settings.bucketSize, hashB, compare), + } +} + +func pipe[X, Y, Z any](a func(X) Y, b func(Y) Z) func(X) Z { + return func(x X) Z { return b(a(x)) } +} + +// NewTableBy creates a [HashTable] for any key type by using keyFunc to derive a +// comparable key. Two keys with the same derived key are treated as equal. +func NewTableBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *HashTable[K, V] { + return NewCustomTable[K, V]( + pipe(keyFunc, NewDefaultHash[C]()), + pipe(keyFunc, NewDefaultHash[C]()), + func(a, b K) bool { return keyFunc(a) == keyFunc(b) }, + options..., + ) +} + +// NewTable creates a [HashTable] using the default [Hash] and [EqualFunc]. Use +// the [Option] functions to configure its behavior. Note that this constructor +// is only provided for comparable keys. For arbitrary keys, consider +// [NewTableBy] or [NewCustomTable]. +func NewTable[K comparable, V any](options ...Option) *HashTable[K, V] { + return NewCustomTable[K, V](NewDefaultHash[K](), NewDefaultHash[K](), DefaultEqualFunc[K], options...) +} diff --git a/table.go b/table.go index 922aa81..c676a5d 100644 --- a/table.go +++ b/table.go @@ -1,237 +1,103 @@ package cuckoo -import ( - "fmt" - "iter" - "math/bits" - "strings" -) - -// A Table is hash table that uses cuckoo hashing to resolve collision. Create -// one with [NewTable]. Or if you want more granularity, use [NewTableBy] or -// [NewCustomTable]. -type Table[K, V any] struct { - bucketA, bucketB bucket[K, V] - growthFactor uint64 - minLoadFactor float64 +type entry[K, V any] struct { + key K + value V } -// TotalCapacity returns the number of slots allocated for the [Table]. To get the -// number of slots filled, look at [Table.Size]. -func (t Table[K, V]) TotalCapacity() uint64 { - return t.bucketA.capacity + t.bucketB.capacity +type slot[K, V any] struct { + entry[K, V] + occupied bool } -// Size returns how many slots are filled in the [Table]. -func (t Table[K, V]) Size() int { - return int(t.bucketA.size + t.bucketB.size) +type table[K, V any] struct { + hash Hash[K] + slots []slot[K, V] + capacity, size uint64 + compare EqualFunc[K] } -func log2(n uint64) (m int) { - return max(0, bits.Len64(n)-1) +// location determines where in the bucket a certain key would be placed. If the +// capacity is 0, this will panic. +func (t table[K, V]) location(key K) uint64 { + return t.hash(key) % t.capacity } -func (t Table[K, V]) maxEvictions() int { - return 3 * log2(t.TotalCapacity()) -} - -func (t Table[K, V]) load() float64 { - // When there are no slots in the table, we still treat the load as 100%. - // Every slot in the table is full. - if t.TotalCapacity() == 0 { - return 1.0 +func (t table[K, V]) get(key K) (value V, found bool) { + if t.capacity == 0 { + return } - return float64(t.Size()) / float64(t.TotalCapacity()) + slot := t.slots[t.location(key)] + return slot.value, slot.occupied && t.compare(slot.key, key) } -// resize clears all buckets, changes the sizes of them to a specific capacity, -// and fills them back up again. It is a helper function for [Table.grow] and -// [Table.shrink]; use them instead. -func (t *Table[K, V]) resize(capacity uint64) error { - entries := make([]entry[K, V], 0, t.Size()) - for k, v := range t.Entries() { - entries = append(entries, entry[K, V]{k, v}) +func (t *table[K, V]) drop(key K) (occupied bool) { + if t.capacity == 0 { + return } - t.bucketA.resize(capacity) - t.bucketB.resize(capacity) + slot := &t.slots[t.location(key)] - for _, entry := range entries { - if err := t.Put(entry.key, entry.value); err != nil { - return err - } + if slot.occupied && t.compare(slot.key, key) { + slot.occupied = false + t.size-- + return true } - return nil + return false } -// grow increases the table's capacity by the [Table.growthFactor]. If the -// capacity is 0, it increases it to 1. -func (t *Table[K, V]) grow() error { - var newCapacity uint64 - - if t.TotalCapacity() == 0 { - newCapacity = 1 - } else { - newCapacity = t.bucketA.capacity * t.growthFactor - } - - return t.resize(newCapacity) +func (t *table[K, V]) resize(capacity uint64) { + t.slots = make([]slot[K, V], capacity) + t.capacity = capacity + t.size = 0 } -// shrink reduces the table's capacity by the [Table.growthFactor]. It may -// reduce it down to 0. -func (t *Table[K, V]) shrink() error { - return t.resize(t.bucketA.capacity / t.growthFactor) +func (t table[K, V]) update(key K, value V) (updated bool) { + if t.capacity == 0 { + return + } + + slot := &t.slots[t.location(key)] + + if slot.occupied && t.compare(slot.key, key) { + slot.value = value + return true + } + + return false } -// Get fetches the value for a key in the [Table]. Returns an error if no value -// is found. -func (t Table[K, V]) Get(key K) (value V, err error) { - if item, ok := t.bucketA.get(key); ok { - return item, nil +func (t *table[K, V]) evict(insertion entry[K, V]) (evicted entry[K, V], eviction bool) { + if t.capacity == 0 { + return insertion, true } - if item, ok := t.bucketB.get(key); ok { - return item, nil + slot := &t.slots[t.location(insertion.key)] + + if !slot.occupied { + slot.entry = insertion + slot.occupied = true + t.size++ + return } - return value, fmt.Errorf("key '%v' not found", key) + if t.compare(slot.key, insertion.key) { + slot.value = insertion.value + return + } + + insertion, slot.entry = slot.entry, insertion + return insertion, true } -// Has returns true if a key has a value in the table. -func (t Table[K, V]) Has(key K) (exists bool) { - _, err := t.Get(key) - return err == nil -} - -// Put sets the value for a key. Returns error if its value cannot be set. -func (t *Table[K, V]) Put(key K, value V) (err error) { - if t.bucketA.update(key, value) { - return nil - } - - if t.bucketB.update(key, value) { - return nil - } - - entry, eviction := entry[K, V]{key, value}, false - for range t.maxEvictions() { - if entry, eviction = t.bucketA.evict(entry); !eviction { - return nil - } - - if entry, eviction = t.bucketB.evict(entry); !eviction { - return nil - } - } - - if t.load() < t.minLoadFactor { - return fmt.Errorf("bad hash: resize on load %d/%d = %f", t.Size(), t.TotalCapacity(), t.load()) - } - - if err := t.grow(); err != nil { - return err - } - - return t.Put(entry.key, entry.value) -} - -// Drop removes a value for a key in the table. Returns an error if its value -// cannot be removed. -func (t *Table[K, V]) Drop(key K) (err error) { - t.bucketA.drop(key) - t.bucketB.drop(key) - - if t.load() < t.minLoadFactor { - return t.shrink() - } - - return nil -} - -// Entries returns an unordered sequence of all key-value pairs in the table. -func (t Table[K, V]) Entries() iter.Seq2[K, V] { - return func(yield func(K, V) bool) { - for _, slot := range t.bucketA.slots { - if slot.occupied { - if !yield(slot.key, slot.value) { - return - } - } - } - - for _, slot := range t.bucketB.slots { - if slot.occupied { - if !yield(slot.key, slot.value) { - return - } - } - } +func newTable[K, V any](capacity uint64, hash Hash[K], compare EqualFunc[K]) table[K, V] { + return table[K, V]{ + hash: hash, + capacity: capacity, + compare: compare, + size: 0, + slots: make([]slot[K, V], capacity), } } - -// String returns the entries of the table as a string in the format: -// "table[k1:v1 h2:v2 ...]". -func (t Table[K, V]) String() string { - var sb strings.Builder - sb.WriteString("table[") - - first := true - for k, v := range t.Entries() { - if !first { - sb.WriteString(" ") - } - - fmt.Fprintf(&sb, "%v:%v", k, v) - first = false - } - - sb.WriteString("]") - return sb.String() -} - -// NewCustomTable creates a [Table] with custom [Hash] and [EqualFunc] -// functions, along with any [Option] the user provides. -func NewCustomTable[K, V any](hashA, hashB Hash[K], compare EqualFunc[K], options ...Option) *Table[K, V] { - settings := &settings{ - growthFactor: DefaultGrowthFactor, - bucketSize: DefaultCapacity, - minLoadFactor: defaultMinimumLoad, - } - - for _, option := range options { - option(settings) - } - - return &Table[K, V]{ - growthFactor: settings.growthFactor, - minLoadFactor: settings.minLoadFactor, - bucketA: newBucket[K, V](settings.bucketSize, hashA, compare), - bucketB: newBucket[K, V](settings.bucketSize, hashB, compare), - } -} - -func pipe[X, Y, Z any](a func(X) Y, b func(Y) Z) func(X) Z { - return func(x X) Z { return b(a(x)) } -} - -// NewTableBy creates a [Table] for any key type by using keyFunc to derive a -// comparable key. Two keys with the same derived key are treated as equal. -func NewTableBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *Table[K, V] { - return NewCustomTable[K, V]( - pipe(keyFunc, NewDefaultHash[C]()), - pipe(keyFunc, NewDefaultHash[C]()), - func(a, b K) bool { return keyFunc(a) == keyFunc(b) }, - options..., - ) -} - -// NewTable creates a [Table] using the default [Hash] and [EqualFunc]. Use -// the [Option] functions to configure its behavior. Note that this constructor -// is only provided for comparable keys. For arbitrary keys, consider -// [NewTableBy] or [NewCustomTable]. -func NewTable[K comparable, V any](options ...Option) *Table[K, V] { - return NewCustomTable[K, V](NewDefaultHash[K](), NewDefaultHash[K](), DefaultEqualFunc[K], options...) -} -- 2.49.1 From 395a3560c7362e4aa6b8bad49ea548d6071e29ea Mon Sep 17 00:00:00 2001 From: "M.V. Hutz" Date: Sat, 4 Apr 2026 12:27:53 +0200 Subject: [PATCH 2/4] refactor: constructors, update docs - NewCustomTable -> NewCustom - NewTableBy -> NewBy - NewTable -> New --- compare.go | 6 +++--- compare_example_test.go | 2 +- cuckoo_fuzz_test.go | 2 +- cuckoo_internal_test.go | 4 ++-- cuckoo_test.go | 32 +++++++++++++++----------------- doc.go | 4 ++-- doc_example_test.go | 2 +- hash.go | 4 ++-- hash_table.go | 24 ++++++++++++------------ settings.go | 18 +++++++++--------- 10 files changed, 48 insertions(+), 50 deletions(-) diff --git a/compare.go b/compare.go index 57f8b47..4a873ad 100644 --- a/compare.go +++ b/compare.go @@ -1,11 +1,11 @@ package cuckoo // An EqualFunc determines whethers two keys are 'equal'. Keys that are 'equal' -// are teated as the same by the [Table]. A good EqualFunc is pure, -// deterministic, and fast. By default, [NewTable] uses [DefaultEqualFunc]. +// are teated as the same by the [HashTable]. A good EqualFunc is pure, +// deterministic, and fast. By default, [New] uses [DefaultEqualFunc]. // // This function MUST NOT return true if the [Hash] digest of two keys -// are different: the [Table] will not work. +// are different: the [HashTable] will not work. type EqualFunc[K any] = func(a, b K) bool // DefaultEqualFunc compares two keys by strict equality. Returns true if the diff --git a/compare_example_test.go b/compare_example_test.go index b41cb3e..daee291 100644 --- a/compare_example_test.go +++ b/compare_example_test.go @@ -28,7 +28,7 @@ func ExampleEqualFunc_badEqualFunc() { // Two users with the same ID are equal. isEqual := func(a, b User) bool { return a.ID == b.ID } - userbase := cuckoo.NewCustomTable[User, bool](makeHash(1), makeHash(2), isEqual) + userbase := cuckoo.NewCustom[User, bool](makeHash(1), makeHash(2), isEqual) (userbase.Put(User{"1", "Robert Doe"}, true)) diff --git a/cuckoo_fuzz_test.go b/cuckoo_fuzz_test.go index f849de0..91f72cd 100644 --- a/cuckoo_fuzz_test.go +++ b/cuckoo_fuzz_test.go @@ -56,7 +56,7 @@ func FuzzInsertLookup(f *testing.F) { fmt.Fprintf(os.Stderr, "seedA=%d seedB=%d capacity=%d growthFactor=%d\n", seedA, seedB, capacity, growthFactor) - actual := cuckoo.NewCustomTable[uint32, uint32]( + actual := cuckoo.NewCustom[uint32, uint32]( offsetHash(seedA), offsetHash(seedB), func(a, b uint32) bool { return a == b }, diff --git a/cuckoo_internal_test.go b/cuckoo_internal_test.go index f2b24a3..461f4d7 100644 --- a/cuckoo_internal_test.go +++ b/cuckoo_internal_test.go @@ -11,7 +11,7 @@ func TestMaxEvictions(t *testing.T) { assert := assert.New(t) for i := 16; i < 116; i++ { - table := NewTable[int, bool](Capacity(i / 2)) + table := New[int, bool](Capacity(i / 2)) expectedEvictions := 3 * math.Floor(math.Log2(float64(i))) assert.Equal(table.maxEvictions(), int(expectedEvictions)) @@ -20,7 +20,7 @@ func TestMaxEvictions(t *testing.T) { func TestLoad(t *testing.T) { assert := assert.New(t) - table := NewTable[int, bool](Capacity(8)) + table := New[int, bool](Capacity(8)) for i := range 16 { err := table.Put(i, true) diff --git a/cuckoo_test.go b/cuckoo_test.go index 131194a..84cf5c0 100644 --- a/cuckoo_test.go +++ b/cuckoo_test.go @@ -14,7 +14,7 @@ import ( func TestNewTable(t *testing.T) { assert := assert.New(t) - table := cuckoo.NewTable[int, bool]() + table := cuckoo.New[int, bool]() assert.NotNil(table) assert.Zero(table.Size()) @@ -23,7 +23,7 @@ func TestNewTable(t *testing.T) { func TestAddItem(t *testing.T) { assert := assert.New(t) key, value := 0, true - table := cuckoo.NewTable[int, bool]() + table := cuckoo.New[int, bool]() err := table.Put(key, value) @@ -35,7 +35,7 @@ func TestAddItem(t *testing.T) { func TestPutOverwrite(t *testing.T) { assert := assert.New(t) key, value, newValue := 0, 1, 2 - table := cuckoo.NewTable[int, int]() + table := cuckoo.New[int, int]() (table.Put(key, value)) err := table.Put(key, newValue) @@ -50,7 +50,7 @@ func TestPutOverwrite(t *testing.T) { func TestSameHash(t *testing.T) { assert := assert.New(t) hash := func(int) uint64 { return 0 } - table := cuckoo.NewCustomTable[int, bool](hash, hash, cuckoo.DefaultEqualFunc[int]) + table := cuckoo.NewCustom[int, bool](hash, hash, cuckoo.DefaultEqualFunc[int]) errA := table.Put(0, true) errB := table.Put(1, true) @@ -63,14 +63,14 @@ func TestSameHash(t *testing.T) { func TestStartingCapacity(t *testing.T) { assert := assert.New(t) - table := cuckoo.NewTable[int, bool](cuckoo.Capacity(64)) + table := cuckoo.New[int, bool](cuckoo.Capacity(64)) assert.Equal(uint64(128), table.TotalCapacity()) } func TestResizeCapacity(t *testing.T) { assert := assert.New(t) - table := cuckoo.NewTable[int, bool]( + table := cuckoo.New[int, bool]( cuckoo.Capacity(8), cuckoo.GrowthFactor(2), ) @@ -85,7 +85,7 @@ func TestResizeCapacity(t *testing.T) { func TestPutMany(t *testing.T) { assert := assert.New(t) - expected, actual := map[int]bool{}, cuckoo.NewTable[int, bool]() + expected, actual := map[int]bool{}, cuckoo.New[int, bool]() for i := range 1_000 { expected[i] = true @@ -100,7 +100,7 @@ func TestPutMany(t *testing.T) { func TestGetMany(t *testing.T) { assert := assert.New(t) - table := cuckoo.NewTable[int, bool]() + table := cuckoo.New[int, bool]() for i := range 1_000 { err := table.Put(i, true) @@ -121,7 +121,7 @@ func TestGetMany(t *testing.T) { func TestDropExistingItem(t *testing.T) { assert := assert.New(t) key, value := 0, true - table := cuckoo.NewTable[int, bool]() + table := cuckoo.New[int, bool]() (table.Put(key, value)) err := table.Drop(key) @@ -134,7 +134,7 @@ func TestDropExistingItem(t *testing.T) { func TestDropNoItem(t *testing.T) { assert := assert.New(t) key := 0 - table := cuckoo.NewTable[int, bool]() + table := cuckoo.New[int, bool]() err := table.Drop(key) @@ -146,7 +146,7 @@ func TestDropNoItem(t *testing.T) { func TestDropItemCapacity(t *testing.T) { assert := assert.New(t) key := 0 - table := cuckoo.NewTable[int, bool]( + table := cuckoo.New[int, bool]( cuckoo.Capacity(64), cuckoo.GrowthFactor(2), ) @@ -164,7 +164,7 @@ func TestDropItemCapacity(t *testing.T) { func TestPutNoCapacity(t *testing.T) { assert := assert.New(t) key, value := 0, true - table := cuckoo.NewTable[int, bool]( + table := cuckoo.New[int, bool]( cuckoo.Capacity(0), ) @@ -177,7 +177,7 @@ func TestPutNoCapacity(t *testing.T) { func TestBadHashCapacity(t *testing.T) { assert := assert.New(t) - table := cuckoo.NewCustomTable[int, bool]( + table := cuckoo.NewCustom[int, bool]( func(int) uint64 { return 0 }, func(int) uint64 { return 0 }, func(a, b int) bool { return a == b }, @@ -197,7 +197,7 @@ func TestBadHashCapacity(t *testing.T) { func TestDropResizeCapacity(t *testing.T) { assert := assert.New(t) - table := cuckoo.NewTable[int, bool]( + table := cuckoo.New[int, bool]( cuckoo.Capacity(10), ) @@ -217,9 +217,7 @@ func TestNewTableBy(t *testing.T) { } assert := assert.New(t) - table := cuckoo.NewTableBy[User, bool]( - func(u User) string { return u.id }, - ) + table := cuckoo.NewBy[User, bool](func(u User) string { return u.id }) err := table.Put(User{nil, "1", "Robert"}, true) diff --git a/doc.go b/doc.go index 11f8cda..3be8bfc 100644 --- a/doc.go +++ b/doc.go @@ -1,8 +1,8 @@ // Package cuckoo provides a hash table that uses cuckoo hashing to achieve // a worst-case O(1) lookup time. // -// While a [NewTable] only supports comparable keys by default, you can create -// a table with any key type using [NewCustomTable]. Custom [Hash] functions and +// While a [New] only supports comparable keys by default, you can create +// a table with any key type using [NewCustom]. Custom [Hash] functions and // key comparison are also supported. // // See more: https://en.wikipedia.org/wiki/Cuckoo_hashing diff --git a/doc_example_test.go b/doc_example_test.go index 1fad4ff..8020324 100644 --- a/doc_example_test.go +++ b/doc_example_test.go @@ -8,7 +8,7 @@ import ( ) func Example_basic() { - table := cuckoo.NewTable[int, string]() + table := cuckoo.New[int, string]() if err := table.Put(1, "Hello, World!"); err != nil { fmt.Println("Put error:", err) diff --git a/hash.go b/hash.go index a83fe55..acf37f5 100644 --- a/hash.go +++ b/hash.go @@ -7,9 +7,9 @@ import ( // A Hash function maps any data to a fixed-length value (in this case, a // [uint64]). // -// It is used by the [Table] to evenly distribute values +// It is used by the [HashTable] to evenly distribute values // amongst its slots. A good hash function is uniform, [chaotic], and -// deterministic. [Table] uses [NewDefaultHash] by default, which is built on +// deterministic. [HashTable] uses [NewDefaultHash] by default, which is built on // [maphash.Comparable]. // // [chaotic]: https://en.wikipedia.org/wiki/Avalanche_effect diff --git a/hash_table.go b/hash_table.go index 9e037ac..25bb155 100644 --- a/hash_table.go +++ b/hash_table.go @@ -7,9 +7,9 @@ import ( "strings" ) -// A HashTable is hash table that uses cuckoo hashing to resolve collision. Create -// one with [NewTable]. Or if you want more granularity, use [NewTableBy] or -// [NewCustomTable]. +// A HashTable which uses cuckoo hashing to resolve collision. Create +// one with [New]. Or if you want more granularity, use [NewBy] or +// [NewCustom]. type HashTable[K, V any] struct { tableA, tableB table[K, V] growthFactor uint64 @@ -192,9 +192,9 @@ func (t *HashTable[K, V]) String() string { return sb.String() } -// NewCustomTable creates a [HashTable] with custom [Hash] and [EqualFunc] +// NewCustom creates a [HashTable] with custom [Hash] and [EqualFunc] // functions, along with any [Option] the user provides. -func NewCustomTable[K, V any](hashA, hashB Hash[K], compare EqualFunc[K], options ...Option) *HashTable[K, V] { +func NewCustom[K, V any](hashA, hashB Hash[K], compare EqualFunc[K], options ...Option) *HashTable[K, V] { settings := &settings{ growthFactor: DefaultGrowthFactor, bucketSize: DefaultCapacity, @@ -217,10 +217,10 @@ func pipe[X, Y, Z any](a func(X) Y, b func(Y) Z) func(X) Z { return func(x X) Z { return b(a(x)) } } -// NewTableBy creates a [HashTable] for any key type by using keyFunc to derive a +// NewBy creates a [HashTable] for any key type by using keyFunc to derive a // comparable key. Two keys with the same derived key are treated as equal. -func NewTableBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *HashTable[K, V] { - return NewCustomTable[K, V]( +func NewBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *HashTable[K, V] { + return NewCustom[K, V]( pipe(keyFunc, NewDefaultHash[C]()), pipe(keyFunc, NewDefaultHash[C]()), func(a, b K) bool { return keyFunc(a) == keyFunc(b) }, @@ -228,10 +228,10 @@ func NewTableBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *H ) } -// NewTable creates a [HashTable] using the default [Hash] and [EqualFunc]. Use +// New creates a [HashTable] using the default [Hash] and [EqualFunc]. Use // the [Option] functions to configure its behavior. Note that this constructor // is only provided for comparable keys. For arbitrary keys, consider -// [NewTableBy] or [NewCustomTable]. -func NewTable[K comparable, V any](options ...Option) *HashTable[K, V] { - return NewCustomTable[K, V](NewDefaultHash[K](), NewDefaultHash[K](), DefaultEqualFunc[K], options...) +// [NewBy] or [NewCustom]. +func New[K comparable, V any](options ...Option) *HashTable[K, V] { + return NewCustom[K, V](NewDefaultHash[K](), NewDefaultHash[K](), DefaultEqualFunc[K], options...) } diff --git a/settings.go b/settings.go index fe0408f..7af5dbf 100644 --- a/settings.go +++ b/settings.go @@ -2,18 +2,18 @@ package cuckoo import "fmt" -// DefaultCapacity is the initial capacity of a [Table]. It is inspired from +// DefaultCapacity is the initial capacity of a [HashTable]. It is inspired from // Java's [HashMap] implementation, which also uses 16. // // [HashMap]: https://docs.oracle.com/javase/8/docs/api/java/util/HashMap.html#HashMap-- const DefaultCapacity uint64 = 16 -// DefaultGrowthFactor is the standard resize multiplier for a [Table]. Most -// hash table implementations use 2. +// DefaultGrowthFactor is the standard resize multiplier for a [HashTable]. Most +// implementations use 2. const DefaultGrowthFactor uint64 = 2 -// defaultMinimumLoad is the default lowest acceptable occupancy of a [Table]. -// The higher the minimum load, the more likely that a [Table.Put] will not +// defaultMinimumLoad is the default lowest acceptable occupancy of a [HashTable]. +// The higher the minimum load, the more likely that a [HashTable.Put] will not // succeed. The value of 5% is taken from [libcuckoo]. // // [libcuckoo]: https://github.com/efficient/libcuckoo/blob/656714705a055df2b7a605eb3c71586d9da1e119/libcuckoo/cuckoohash_config.hh#L21 @@ -25,11 +25,11 @@ type settings struct { bucketSize uint64 } -// An Option modifies the settings of a [Table]. It is used in its constructors -// like [NewTable], for example. +// An Option modifies the settings of a [HashTable]. It is used in its constructors +// like [New], for example. type Option func(*settings) -// Capacity modifies the starting capacity of each bucket of the [Table]. The +// Capacity modifies the starting capacity of each bucket of the [HashTable]. The // value must be non-negative. func Capacity(value int) Option { if value < 0 { @@ -39,7 +39,7 @@ func Capacity(value int) Option { return func(s *settings) { s.bucketSize = uint64(value) } } -// GrowthFactor controls how much the capacity of the [Table] multiplies when +// GrowthFactor controls how much the capacity of the [HashTable] multiplies when // it must resize. The value must be greater than 1. func GrowthFactor(value int) Option { if value < 2 { -- 2.49.1 From 6a5b40c09716d33d67038823ccbe1039346088ac Mon Sep 17 00:00:00 2001 From: "M.V. Hutz" Date: Mon, 13 Apr 2026 20:49:33 -0400 Subject: [PATCH 3/4] docs: replaced instances of "bucket" with "table" - Removed instances of `growthFactor`, as it is unexported. - Typo in `HashTable.String()`. --- hash_table.go | 8 ++++---- settings.go | 2 +- table.go | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/hash_table.go b/hash_table.go index 25bb155..fde9d3e 100644 --- a/hash_table.go +++ b/hash_table.go @@ -45,7 +45,7 @@ func (t *HashTable[K, V]) load() float64 { return float64(t.Size()) / float64(t.TotalCapacity()) } -// resize clears all buckets, changes the sizes of them to a specific capacity, +// resize clears all tables, changes the sizes of them to a specific capacity, // and fills them back up again. It is a helper function for [HashTable.grow] and // [HashTable.shrink]; use them instead. func (t *HashTable[K, V]) resize(capacity uint64) error { @@ -66,7 +66,7 @@ func (t *HashTable[K, V]) resize(capacity uint64) error { return nil } -// grow increases the table's capacity by the [HashTable.growthFactor]. If the +// grow increases the table's capacity by the growth factor. If the // capacity is 0, it increases it to 1. func (t *HashTable[K, V]) grow() error { var newCapacity uint64 @@ -80,7 +80,7 @@ func (t *HashTable[K, V]) grow() error { return t.resize(newCapacity) } -// shrink reduces the table's capacity by the [HashTable.growthFactor]. It may +// shrink reduces the table's capacity by the growth factor. It may // reduce it down to 0. func (t *HashTable[K, V]) shrink() error { return t.resize(t.tableA.capacity / t.growthFactor) @@ -173,7 +173,7 @@ func (t *HashTable[K, V]) Entries() iter.Seq2[K, V] { } // String returns the entries of the table as a string in the format: -// "table[k1:v1 h2:v2 ...]". +// "table[k1:v1 k2:v2 ...]". func (t *HashTable[K, V]) String() string { var sb strings.Builder sb.WriteString("table[") diff --git a/settings.go b/settings.go index 7af5dbf..28cad7a 100644 --- a/settings.go +++ b/settings.go @@ -29,7 +29,7 @@ type settings struct { // like [New], for example. type Option func(*settings) -// Capacity modifies the starting capacity of each bucket of the [HashTable]. The +// Capacity modifies the starting capacity of each table of the [HashTable]. The // value must be non-negative. func Capacity(value int) Option { if value < 0 { diff --git a/table.go b/table.go index c676a5d..b3247e0 100644 --- a/table.go +++ b/table.go @@ -17,7 +17,7 @@ type table[K, V any] struct { compare EqualFunc[K] } -// location determines where in the bucket a certain key would be placed. If the +// location determines where in the table a certain key would be placed. If the // capacity is 0, this will panic. func (t table[K, V]) location(key K) uint64 { return t.hash(key) % t.capacity -- 2.49.1 From 5c39182958c2a14dc31a0c1c8dce66fc54da713c Mon Sep 17 00:00:00 2001 From: "M.V. Hutz" Date: Mon, 13 Apr 2026 21:11:37 -0400 Subject: [PATCH 4/4] refactor: HashTable -> Table, table -> subtable --- compare.go | 4 +- hash.go | 4 +- hash_table.go | 246 ------------------------------------------- settings.go | 14 +-- subtable.go | 103 ++++++++++++++++++ table.go | 283 +++++++++++++++++++++++++++++++++++++------------- 6 files changed, 327 insertions(+), 327 deletions(-) delete mode 100644 hash_table.go create mode 100644 subtable.go diff --git a/compare.go b/compare.go index 4a873ad..953ccd9 100644 --- a/compare.go +++ b/compare.go @@ -1,11 +1,11 @@ package cuckoo // An EqualFunc determines whethers two keys are 'equal'. Keys that are 'equal' -// are teated as the same by the [HashTable]. A good EqualFunc is pure, +// are teated as the same by the [Table]. A good EqualFunc is pure, // deterministic, and fast. By default, [New] uses [DefaultEqualFunc]. // // This function MUST NOT return true if the [Hash] digest of two keys -// are different: the [HashTable] will not work. +// are different: the [Table] will not work. type EqualFunc[K any] = func(a, b K) bool // DefaultEqualFunc compares two keys by strict equality. Returns true if the diff --git a/hash.go b/hash.go index acf37f5..a83fe55 100644 --- a/hash.go +++ b/hash.go @@ -7,9 +7,9 @@ import ( // A Hash function maps any data to a fixed-length value (in this case, a // [uint64]). // -// It is used by the [HashTable] to evenly distribute values +// It is used by the [Table] to evenly distribute values // amongst its slots. A good hash function is uniform, [chaotic], and -// deterministic. [HashTable] uses [NewDefaultHash] by default, which is built on +// deterministic. [Table] uses [NewDefaultHash] by default, which is built on // [maphash.Comparable]. // // [chaotic]: https://en.wikipedia.org/wiki/Avalanche_effect diff --git a/hash_table.go b/hash_table.go deleted file mode 100644 index 324a6d6..0000000 --- a/hash_table.go +++ /dev/null @@ -1,246 +0,0 @@ -package cuckoo - -import ( - "errors" - "fmt" - "iter" - "math/bits" - "strings" -) - -// ErrBadHash occurs when the hashes given to a [Table] cause too many key -// collisions. Try rebuilding the table using: -// -// 1. Different hash seeds. Equal seeds produce equal hash functions, which -// always cycle. -// 2. A different [Hash] algorithm. -var ErrBadHash = errors.New("bad hash") - -// A HashTable which uses cuckoo hashing to resolve collision. Create -// one with [New]. Or if you want more granularity, use [NewBy] or -// [NewCustom]. -type HashTable[K, V any] struct { - tableA, tableB table[K, V] - growthFactor uint64 - minLoadFactor float64 -} - -// TotalCapacity returns the number of slots allocated for the [HashTable]. To get the -// number of slots filled, look at [HashTable.Size]. -func (t *HashTable[K, V]) TotalCapacity() uint64 { - return t.tableA.capacity + t.tableB.capacity -} - -// Size returns how many slots are filled in the [HashTable]. -func (t *HashTable[K, V]) Size() int { - return int(t.tableA.size + t.tableB.size) -} - -func log2(n uint64) (m int) { - return max(0, bits.Len64(n)-1) -} - -func (t *HashTable[K, V]) maxEvictions() int { - return 3 * log2(t.TotalCapacity()) -} - -func (t *HashTable[K, V]) load() float64 { - // When there are no slots in the table, we still treat the load as 100%. - // Every slot in the table is full. - if t.TotalCapacity() == 0 { - return 1.0 - } - - return float64(t.Size()) / float64(t.TotalCapacity()) -} - -// resize clears all tables, changes the sizes of them to a specific capacity, -// and fills them back up again. It is a helper function for [HashTable.grow] and -// [HashTable.shrink]; use them instead. -func (t *HashTable[K, V]) resize(capacity uint64) error { - entries := make([]entry[K, V], 0, t.Size()) - for k, v := range t.Entries() { - entries = append(entries, entry[K, V]{k, v}) - } - - t.tableA.resize(capacity) - t.tableB.resize(capacity) - - for _, entry := range entries { - if err := t.Put(entry.key, entry.value); err != nil { - return err - } - } - - return nil -} - -// grow increases the table's capacity by the growth factor. If the -// capacity is 0, it increases it to 1. -func (t *HashTable[K, V]) grow() error { - var newCapacity uint64 - - if t.TotalCapacity() == 0 { - newCapacity = 1 - } else { - newCapacity = t.tableA.capacity * t.growthFactor - } - - return t.resize(newCapacity) -} - -// shrink reduces the table's capacity by the growth factor. It may -// reduce it down to 0. -func (t *HashTable[K, V]) shrink() error { - return t.resize(t.tableA.capacity / t.growthFactor) -} - -// Get fetches the value for a key in the [HashTable]. Returns an error if no value -// is found. -func (t *HashTable[K, V]) Get(key K) (value V, err error) { - if item, ok := t.tableA.get(key); ok { - return item, nil - } - - if item, ok := t.tableB.get(key); ok { - return item, nil - } - - return value, fmt.Errorf("key '%v' not found", key) -} - -// Has returns true if a key has a value in the table. -func (t *HashTable[K, V]) Has(key K) (exists bool) { - _, err := t.Get(key) - return err == nil -} - -// Put sets the value for a key. Returns error if its value cannot be set. -func (t *HashTable[K, V]) Put(key K, value V) (err error) { - if t.tableA.update(key, value) { - return nil - } - - if t.tableB.update(key, value) { - return nil - } - - entry, eviction := entry[K, V]{key, value}, false - for range t.maxEvictions() { - if entry, eviction = t.tableA.evict(entry); !eviction { - return nil - } - - if entry, eviction = t.tableB.evict(entry); !eviction { - return nil - } - } - - if t.load() < t.minLoadFactor { - return fmt.Errorf("hash functions produced a cycle at load %d/%d: %w", t.Size(), t.TotalCapacity(), ErrBadHash) - } - - if err := t.grow(); err != nil { - return err - } - - return t.Put(entry.key, entry.value) -} - -// Drop removes a value for a key in the table. Returns an error if its value -// cannot be removed. -func (t *HashTable[K, V]) Drop(key K) (err error) { - t.tableA.drop(key) - t.tableB.drop(key) - - if t.load() < t.minLoadFactor { - return t.shrink() - } - - return nil -} - -// Entries returns an unordered sequence of all key-value pairs in the table. -func (t *HashTable[K, V]) Entries() iter.Seq2[K, V] { - return func(yield func(K, V) bool) { - for _, slot := range t.tableA.slots { - if slot.occupied { - if !yield(slot.key, slot.value) { - return - } - } - } - - for _, slot := range t.tableB.slots { - if slot.occupied { - if !yield(slot.key, slot.value) { - return - } - } - } - } -} - -// String returns the entries of the table as a string in the format: -// "table[k1:v1 k2:v2 ...]". -func (t *HashTable[K, V]) String() string { - var sb strings.Builder - sb.WriteString("table[") - - first := true - for k, v := range t.Entries() { - if !first { - sb.WriteString(" ") - } - - fmt.Fprintf(&sb, "%v:%v", k, v) - first = false - } - - sb.WriteString("]") - return sb.String() -} - -// NewCustom creates a [HashTable] with custom [Hash] and [EqualFunc] -// functions, along with any [Option] the user provides. -func NewCustom[K, V any](hashA, hashB Hash[K], compare EqualFunc[K], options ...Option) *HashTable[K, V] { - settings := &settings{ - growthFactor: DefaultGrowthFactor, - bucketSize: DefaultCapacity, - minLoadFactor: defaultMinimumLoad, - } - - for _, option := range options { - option(settings) - } - - return &HashTable[K, V]{ - growthFactor: settings.growthFactor, - minLoadFactor: settings.minLoadFactor, - tableA: newTable[K, V](settings.bucketSize, hashA, compare), - tableB: newTable[K, V](settings.bucketSize, hashB, compare), - } -} - -func pipe[X, Y, Z any](a func(X) Y, b func(Y) Z) func(X) Z { - return func(x X) Z { return b(a(x)) } -} - -// NewBy creates a [HashTable] for any key type by using keyFunc to derive a -// comparable key. Two keys with the same derived key are treated as equal. -func NewBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *HashTable[K, V] { - return NewCustom[K, V]( - pipe(keyFunc, NewDefaultHash[C]()), - pipe(keyFunc, NewDefaultHash[C]()), - func(a, b K) bool { return keyFunc(a) == keyFunc(b) }, - options..., - ) -} - -// New creates a [HashTable] using the default [Hash] and [EqualFunc]. Use -// the [Option] functions to configure its behavior. Note that this constructor -// is only provided for comparable keys. For arbitrary keys, consider -// [NewBy] or [NewCustom]. -func New[K comparable, V any](options ...Option) *HashTable[K, V] { - return NewCustom[K, V](NewDefaultHash[K](), NewDefaultHash[K](), DefaultEqualFunc[K], options...) -} diff --git a/settings.go b/settings.go index 28cad7a..97c6e0a 100644 --- a/settings.go +++ b/settings.go @@ -2,18 +2,18 @@ package cuckoo import "fmt" -// DefaultCapacity is the initial capacity of a [HashTable]. It is inspired from +// DefaultCapacity is the initial capacity of a [Table]. It is inspired from // Java's [HashMap] implementation, which also uses 16. // // [HashMap]: https://docs.oracle.com/javase/8/docs/api/java/util/HashMap.html#HashMap-- const DefaultCapacity uint64 = 16 -// DefaultGrowthFactor is the standard resize multiplier for a [HashTable]. Most +// DefaultGrowthFactor is the standard resize multiplier for a [Table]. Most // implementations use 2. const DefaultGrowthFactor uint64 = 2 -// defaultMinimumLoad is the default lowest acceptable occupancy of a [HashTable]. -// The higher the minimum load, the more likely that a [HashTable.Put] will not +// defaultMinimumLoad is the default lowest acceptable occupancy of a [Table]. +// The higher the minimum load, the more likely that a [Table.Put] will not // succeed. The value of 5% is taken from [libcuckoo]. // // [libcuckoo]: https://github.com/efficient/libcuckoo/blob/656714705a055df2b7a605eb3c71586d9da1e119/libcuckoo/cuckoohash_config.hh#L21 @@ -25,11 +25,11 @@ type settings struct { bucketSize uint64 } -// An Option modifies the settings of a [HashTable]. It is used in its constructors +// An Option modifies the settings of a [Table]. It is used in its constructors // like [New], for example. type Option func(*settings) -// Capacity modifies the starting capacity of each table of the [HashTable]. The +// Capacity modifies the starting capacity of each subtable of the [Table]. The // value must be non-negative. func Capacity(value int) Option { if value < 0 { @@ -39,7 +39,7 @@ func Capacity(value int) Option { return func(s *settings) { s.bucketSize = uint64(value) } } -// GrowthFactor controls how much the capacity of the [HashTable] multiplies when +// GrowthFactor controls how much the capacity of the [Table] multiplies when // it must resize. The value must be greater than 1. func GrowthFactor(value int) Option { if value < 2 { diff --git a/subtable.go b/subtable.go new file mode 100644 index 0000000..749d16d --- /dev/null +++ b/subtable.go @@ -0,0 +1,103 @@ +package cuckoo + +type entry[K, V any] struct { + key K + value V +} + +type slot[K, V any] struct { + entry[K, V] + occupied bool +} + +type subtable[K, V any] struct { + hash Hash[K] + slots []slot[K, V] + capacity, size uint64 + compare EqualFunc[K] +} + +// location determines where in the subtable a certain key would be placed. If +// the capacity is 0, this will panic. +func (t subtable[K, V]) location(key K) uint64 { + return t.hash(key) % t.capacity +} + +func (t subtable[K, V]) get(key K) (value V, found bool) { + if t.capacity == 0 { + return + } + + slot := t.slots[t.location(key)] + return slot.value, slot.occupied && t.compare(slot.key, key) +} + +func (t *subtable[K, V]) drop(key K) (occupied bool) { + if t.capacity == 0 { + return + } + + slot := &t.slots[t.location(key)] + + if slot.occupied && t.compare(slot.key, key) { + slot.occupied = false + t.size-- + return true + } + + return false +} + +func (t *subtable[K, V]) resize(capacity uint64) { + t.slots = make([]slot[K, V], capacity) + t.capacity = capacity + t.size = 0 +} + +func (t subtable[K, V]) update(key K, value V) (updated bool) { + if t.capacity == 0 { + return + } + + slot := &t.slots[t.location(key)] + + if slot.occupied && t.compare(slot.key, key) { + slot.value = value + return true + } + + return false +} + +func (t *subtable[K, V]) evict(insertion entry[K, V]) (evicted entry[K, V], eviction bool) { + if t.capacity == 0 { + return insertion, true + } + + slot := &t.slots[t.location(insertion.key)] + + if !slot.occupied { + slot.entry = insertion + slot.occupied = true + t.size++ + return + } + + if t.compare(slot.key, insertion.key) { + slot.value = insertion.value + return + } + + insertion, slot.entry = slot.entry, insertion + return insertion, true +} + +func newSubtable[K, V any](capacity uint64, hash Hash[K], compare EqualFunc[K]) subtable[K, V] { + return subtable[K, V]{ + hash: hash, + capacity: capacity, + compare: compare, + size: 0, + slots: make([]slot[K, V], capacity), + } +} diff --git a/table.go b/table.go index b3247e0..7310101 100644 --- a/table.go +++ b/table.go @@ -1,103 +1,246 @@ package cuckoo -type entry[K, V any] struct { - key K - value V +import ( + "errors" + "fmt" + "iter" + "math/bits" + "strings" +) + +// ErrBadHash occurs when the hashes given to a [Table] cause too many key +// collisions. Try rebuilding the table using: +// +// 1. Different hash seeds. Equal seeds produce equal hash functions, which +// always cycle. +// 2. A different [Hash] algorithm. +var ErrBadHash = errors.New("bad hash") + +// A Table which uses cuckoo hashing to resolve collision. Create +// one with [New]. Or if you want more granularity, use [NewBy] or +// [NewCustom]. +type Table[K, V any] struct { + tableA, tableB subtable[K, V] + growthFactor uint64 + minLoadFactor float64 } -type slot[K, V any] struct { - entry[K, V] - occupied bool +// TotalCapacity returns the number of slots allocated for the [Table]. To get the +// number of slots filled, look at [Table.Size]. +func (t *Table[K, V]) TotalCapacity() uint64 { + return t.tableA.capacity + t.tableB.capacity } -type table[K, V any] struct { - hash Hash[K] - slots []slot[K, V] - capacity, size uint64 - compare EqualFunc[K] +// Size returns how many slots are filled in the [Table]. +func (t *Table[K, V]) Size() int { + return int(t.tableA.size + t.tableB.size) } -// location determines where in the table a certain key would be placed. If the -// capacity is 0, this will panic. -func (t table[K, V]) location(key K) uint64 { - return t.hash(key) % t.capacity +func log2(n uint64) (m int) { + return max(0, bits.Len64(n)-1) } -func (t table[K, V]) get(key K) (value V, found bool) { - if t.capacity == 0 { - return +func (t *Table[K, V]) maxEvictions() int { + return 3 * log2(t.TotalCapacity()) +} + +func (t *Table[K, V]) load() float64 { + // When there are no slots in the table, we still treat the load as 100%. + // Every slot in the table is full. + if t.TotalCapacity() == 0 { + return 1.0 } - slot := t.slots[t.location(key)] - return slot.value, slot.occupied && t.compare(slot.key, key) + return float64(t.Size()) / float64(t.TotalCapacity()) } -func (t *table[K, V]) drop(key K) (occupied bool) { - if t.capacity == 0 { - return +// resize clears all tables, changes the sizes of them to a specific capacity, +// and fills them back up again. It is a helper function for [Table.grow] and +// [Table.shrink]; use them instead. +func (t *Table[K, V]) resize(capacity uint64) error { + entries := make([]entry[K, V], 0, t.Size()) + for k, v := range t.Entries() { + entries = append(entries, entry[K, V]{k, v}) } - slot := &t.slots[t.location(key)] + t.tableA.resize(capacity) + t.tableB.resize(capacity) - if slot.occupied && t.compare(slot.key, key) { - slot.occupied = false - t.size-- - return true + for _, entry := range entries { + if err := t.Put(entry.key, entry.value); err != nil { + return err + } } - return false + return nil } -func (t *table[K, V]) resize(capacity uint64) { - t.slots = make([]slot[K, V], capacity) - t.capacity = capacity - t.size = 0 +// grow increases the table's capacity by the growth factor. If the +// capacity is 0, it increases it to 1. +func (t *Table[K, V]) grow() error { + var newCapacity uint64 + + if t.TotalCapacity() == 0 { + newCapacity = 1 + } else { + newCapacity = t.tableA.capacity * t.growthFactor + } + + return t.resize(newCapacity) } -func (t table[K, V]) update(key K, value V) (updated bool) { - if t.capacity == 0 { - return - } - - slot := &t.slots[t.location(key)] - - if slot.occupied && t.compare(slot.key, key) { - slot.value = value - return true - } - - return false +// shrink reduces the table's capacity by the growth factor. It may +// reduce it down to 0. +func (t *Table[K, V]) shrink() error { + return t.resize(t.tableA.capacity / t.growthFactor) } -func (t *table[K, V]) evict(insertion entry[K, V]) (evicted entry[K, V], eviction bool) { - if t.capacity == 0 { - return insertion, true +// Get fetches the value for a key in the [Table]. Returns an error if no value +// is found. +func (t *Table[K, V]) Get(key K) (value V, err error) { + if item, ok := t.tableA.get(key); ok { + return item, nil } - slot := &t.slots[t.location(insertion.key)] - - if !slot.occupied { - slot.entry = insertion - slot.occupied = true - t.size++ - return + if item, ok := t.tableB.get(key); ok { + return item, nil } - if t.compare(slot.key, insertion.key) { - slot.value = insertion.value - return - } - - insertion, slot.entry = slot.entry, insertion - return insertion, true + return value, fmt.Errorf("key '%v' not found", key) } -func newTable[K, V any](capacity uint64, hash Hash[K], compare EqualFunc[K]) table[K, V] { - return table[K, V]{ - hash: hash, - capacity: capacity, - compare: compare, - size: 0, - slots: make([]slot[K, V], capacity), +// Has returns true if a key has a value in the table. +func (t *Table[K, V]) Has(key K) (exists bool) { + _, err := t.Get(key) + return err == nil +} + +// Put sets the value for a key. Returns error if its value cannot be set. +func (t *Table[K, V]) Put(key K, value V) (err error) { + if t.tableA.update(key, value) { + return nil + } + + if t.tableB.update(key, value) { + return nil + } + + entry, eviction := entry[K, V]{key, value}, false + for range t.maxEvictions() { + if entry, eviction = t.tableA.evict(entry); !eviction { + return nil + } + + if entry, eviction = t.tableB.evict(entry); !eviction { + return nil + } + } + + if t.load() < t.minLoadFactor { + return fmt.Errorf("hash functions produced a cycle at load %d/%d: %w", t.Size(), t.TotalCapacity(), ErrBadHash) + } + + if err := t.grow(); err != nil { + return err + } + + return t.Put(entry.key, entry.value) +} + +// Drop removes a value for a key in the table. Returns an error if its value +// cannot be removed. +func (t *Table[K, V]) Drop(key K) (err error) { + t.tableA.drop(key) + t.tableB.drop(key) + + if t.load() < t.minLoadFactor { + return t.shrink() + } + + return nil +} + +// Entries returns an unordered sequence of all key-value pairs in the table. +func (t *Table[K, V]) Entries() iter.Seq2[K, V] { + return func(yield func(K, V) bool) { + for _, slot := range t.tableA.slots { + if slot.occupied { + if !yield(slot.key, slot.value) { + return + } + } + } + + for _, slot := range t.tableB.slots { + if slot.occupied { + if !yield(slot.key, slot.value) { + return + } + } + } } } + +// String returns the entries of the table as a string in the format: +// "table[k1:v1 k2:v2 ...]". +func (t *Table[K, V]) String() string { + var sb strings.Builder + sb.WriteString("table[") + + first := true + for k, v := range t.Entries() { + if !first { + sb.WriteString(" ") + } + + fmt.Fprintf(&sb, "%v:%v", k, v) + first = false + } + + sb.WriteString("]") + return sb.String() +} + +// NewCustom creates a [Table] with custom [Hash] and [EqualFunc] +// functions, along with any [Option] the user provides. +func NewCustom[K, V any](hashA, hashB Hash[K], compare EqualFunc[K], options ...Option) *Table[K, V] { + settings := &settings{ + growthFactor: DefaultGrowthFactor, + bucketSize: DefaultCapacity, + minLoadFactor: defaultMinimumLoad, + } + + for _, option := range options { + option(settings) + } + + return &Table[K, V]{ + growthFactor: settings.growthFactor, + minLoadFactor: settings.minLoadFactor, + tableA: newSubtable[K, V](settings.bucketSize, hashA, compare), + tableB: newSubtable[K, V](settings.bucketSize, hashB, compare), + } +} + +func pipe[X, Y, Z any](a func(X) Y, b func(Y) Z) func(X) Z { + return func(x X) Z { return b(a(x)) } +} + +// NewBy creates a [Table] for any key type by using keyFunc to derive a +// comparable key. Two keys with the same derived key are treated as equal. +func NewBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *Table[K, V] { + return NewCustom[K, V]( + pipe(keyFunc, NewDefaultHash[C]()), + pipe(keyFunc, NewDefaultHash[C]()), + func(a, b K) bool { return keyFunc(a) == keyFunc(b) }, + options..., + ) +} + +// New creates a [Table] using the default [Hash] and [EqualFunc]. Use +// the [Option] functions to configure its behavior. Note that this constructor +// is only provided for comparable keys. For arbitrary keys, consider +// [NewBy] or [NewCustom]. +func New[K comparable, V any](options ...Option) *Table[K, V] { + return NewCustom[K, V](NewDefaultHash[K](), NewDefaultHash[K](), DefaultEqualFunc[K], options...) +} -- 2.49.1