diff --git a/.golangci.yml b/.golangci.yml index 1ec3d80..795e81b 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -114,6 +114,9 @@ linters: # Reports uses of functions with replacement inside the testing package. - usetesting + # Reports mixed receiver types in structs/interfaces. + - recvcheck + settings: revive: rules: @@ -198,7 +201,7 @@ linters: # warns when initialism, variable or package naming conventions are not followed. - name: var-naming - + misspell: # Correct spellings using locale preferences for US or UK. # Setting locale to US will correct the British spelling of 'colour' to 'color'. diff --git a/compare.go b/compare.go index 57f8b47..953ccd9 100644 --- a/compare.go +++ b/compare.go @@ -2,7 +2,7 @@ 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]. +// 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. 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 51aa112..7c6af28 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 }, @@ -74,16 +74,16 @@ func FuzzInsertLookup(f *testing.F) { delete(expected, step.key) - _, err := actual.Get(step.key) - assert.Error(err) + _, ok = actual.Get(step.key) + assert.True(ok) } else { _, err := actual.Put(step.key, step.value) assert.NoError(err) expected[step.key] = step.value - found, err := actual.Get(step.key) - assert.NoError(err) + found, ok := actual.Get(step.key) + assert.True(ok) assert.Equal(step.value, found) } diff --git a/cuckoo_internal_test.go b/cuckoo_internal_test.go index ec07056..d34852a 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 738e501..d0d1ae3 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) @@ -108,12 +108,12 @@ func TestGetMany(t *testing.T) { } for i := range 2_000 { - value, err := table.Get(i) + value, ok := table.Get(i) if i < 1_000 { - assert.NoError(err) + assert.True(ok) assert.Equal(value, true) } else { - assert.Error(err) + assert.False(ok) } } } @@ -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)) had := 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]() had := 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), ) @@ -163,7 +163,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), ) @@ -176,7 +176,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 }, @@ -196,7 +196,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), ) @@ -216,9 +216,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 86f8e0c..63ea8f1 100644 --- a/doc_example_test.go +++ b/doc_example_test.go @@ -8,25 +8,25 @@ 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) } - if item, err := table.Get(1); err != nil { - fmt.Println("Error:", err) + if item, ok := table.Get(1); !ok { + fmt.Println("Not Found 1!") } else { fmt.Println("Found 1:", item) } - if item, err := table.Get(0); err != nil { - fmt.Println("Error:", err) + if item, ok := table.Get(0); !ok { + fmt.Println("Not Found 0!") } else { fmt.Println("Found 0:", item) } // Output: // Found 1: Hello, World! - // Error: key '0' not found + // Not Found 0! } diff --git a/settings.go b/settings.go index 425d6ba..a527e76 100644 --- a/settings.go +++ b/settings.go @@ -9,7 +9,7 @@ import "fmt" const DefaultCapacity uint64 = 16 // DefaultGrowthFactor is the standard resize multiplier for a [Table]. Most -// hash table implementations use 2. +// implementations use 2. const DefaultGrowthFactor uint64 = 2 // defaultMinimumLoad is the default lowest acceptable occupancy of a [Table]. @@ -31,10 +31,10 @@ type settings struct { } // An Option modifies the settings of a [Table]. It is used in its constructors -// like [NewTable], for example. +// 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 subtable of the [Table]. The // value must be non-negative. func Capacity(value int) Option { if value < 0 { diff --git a/bucket.go b/subtable.go similarity index 72% rename from bucket.go rename to subtable.go index 3a3b1da..f502bcf 100644 --- a/bucket.go +++ b/subtable.go @@ -11,7 +11,7 @@ type slot[K, V any] struct { occupied bool } -type bucket[K, V any] struct { +type subtable[K, V any] struct { hash Hash[K] slots []slot[K, V] capacity, size uint64 @@ -20,11 +20,11 @@ type bucket[K, V any] struct { // 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 { +func (b *subtable[K, V]) location(key K) uint64 { return b.hash(key) % b.capacity } -func (b bucket[K, V]) get(key K) (value V, found bool) { +func (b *subtable[K, V]) get(key K) (value V, found bool) { if b.capacity == 0 { return } @@ -33,7 +33,7 @@ func (b bucket[K, V]) get(key K) (value V, found bool) { return slot.Value, slot.occupied && b.compare(slot.Key, key) } -func (b *bucket[K, V]) drop(key K) (occupied bool) { +func (b *subtable[K, V]) drop(key K) (occupied bool) { if b.capacity == 0 { return } @@ -49,8 +49,8 @@ func (b *bucket[K, V]) drop(key K) (occupied bool) { return false } -func (b *bucket[K, V]) resized(capacity uint64) bucket[K, V] { - return bucket[K, V]{ +func (b *subtable[K, V]) resized(capacity uint64) *subtable[K, V] { + return &subtable[K, V]{ slots: make([]slot[K, V], capacity), capacity: capacity, hash: b.hash, @@ -58,7 +58,7 @@ func (b *bucket[K, V]) resized(capacity uint64) bucket[K, V] { } } -func (b bucket[K, V]) update(key K, value V) (updated bool) { +func (b *subtable[K, V]) update(key K, value V) (updated bool) { if b.capacity == 0 { return } @@ -73,7 +73,7 @@ func (b bucket[K, V]) update(key K, value V) (updated bool) { return false } -func (b *bucket[K, V]) insert(insertion Entry[K, V]) (evicted Entry[K, V], eviction bool) { +func (b *subtable[K, V]) insert(insertion Entry[K, V]) (evicted Entry[K, V], eviction bool) { if b.capacity == 0 { return insertion, true } @@ -96,8 +96,8 @@ func (b *bucket[K, V]) insert(insertion Entry[K, V]) (evicted Entry[K, V], evict return insertion, true } -func newBucket[K, V any](capacity uint64, hash Hash[K], compare EqualFunc[K]) bucket[K, V] { - return bucket[K, V]{ +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, diff --git a/table.go b/table.go index fbfde2b..322e950 100644 --- a/table.go +++ b/table.go @@ -1,41 +1,50 @@ package cuckoo import ( + "errors" "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]. +// 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 { - bucketA, bucketB bucket[K, V] - growthFactor uint64 - minLoadFactor float64 + tableA, tableB *subtable[K, V] + growthFactor uint64 + minLoadFactor float64 } // 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 +func (t *Table[K, V]) TotalCapacity() uint64 { + return t.tableA.capacity + t.tableB.capacity } // 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) +func (t *Table[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 Table[K, V]) maxEvictions() int { +func (t *Table[K, V]) maxEvictions() int { return 3 * log2(t.TotalCapacity()) } -func (t Table[K, V]) load() float64 { +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 { @@ -49,20 +58,20 @@ func (t Table[K, V]) load() float64 { // size of the table. Returns a displaced entry and 'homeless = true' if an // entry could not be placed after exhausting evictions. func (t *Table[K, V]) insert(entry Entry[K, V]) (displaced Entry[K, V], homeless bool) { - if t.bucketA.update(entry.Key, entry.Value) { + if t.tableA.update(entry.Key, entry.Value) { return } - if t.bucketB.update(entry.Key, entry.Value) { + if t.tableB.update(entry.Key, entry.Value) { return } for range t.maxEvictions() { - if entry, homeless = t.bucketA.insert(entry); !homeless { + if entry, homeless = t.tableA.insert(entry); !homeless { return } - if entry, homeless = t.bucketB.insert(entry); !homeless { + if entry, homeless = t.tableB.insert(entry); !homeless { return } } @@ -72,12 +81,12 @@ func (t *Table[K, V]) insert(entry Entry[K, V]) (displaced Entry[K, V], homeless // resized creates an empty copy of the table, with a new capacity for each // bucket. -func (t Table[K, V]) resized(capacity uint64) Table[K, V] { - return Table[K, V]{ +func (t *Table[K, V]) resized(capacity uint64) *Table[K, V] { + return &Table[K, V]{ growthFactor: t.growthFactor, minLoadFactor: t.minLoadFactor, - bucketA: t.bucketA.resized(capacity), - bucketB: t.bucketB.resized(capacity), + tableA: t.tableA.resized(capacity), + tableB: t.tableB.resized(capacity), } } @@ -93,11 +102,11 @@ func (t *Table[K, V]) resize(capacity uint64) bool { } } - *t = updated + *t = *updated return true } -// grow increases the table's capacity by the [Table.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 *Table[K, V]) grow() bool { var newCapacity uint64 @@ -105,36 +114,43 @@ func (t *Table[K, V]) grow() bool { if t.TotalCapacity() == 0 { newCapacity = 1 } else { - newCapacity = t.bucketA.capacity * t.growthFactor + newCapacity = t.tableA.capacity * t.growthFactor } return t.resize(newCapacity) } -// shrink reduces the table's capacity by the [Table.growthFactor]. It may +// shrink reduces the table's capacity by the growth factor. It may // reduce it down to 0. func (t *Table[K, V]) shrink() bool { - return t.resize(t.bucketA.capacity / t.growthFactor) + return t.resize(t.tableA.capacity / t.growthFactor) } -// 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 +// Get fetches the value for a key in the [Table]. Matches the comma-ok pattern +// of a builtin map; see [Table.Find] for plain indexing. +func (t *Table[K, V]) Get(key K) (value V, ok bool) { + if item, ok := t.tableA.get(key); ok { + return item, true } - if item, ok := t.bucketB.get(key); ok { - return item, nil + if item, ok := t.tableB.get(key); ok { + return item, true } - return value, fmt.Errorf("key '%v' not found", key) + return +} + +// Find fetches the value of a key. Matches direct indexing of a builtin map; +// see [Table.Get] for a comma-ok pattern. +func (t *Table[K, V]) Find(key K) (value V) { + value, _ = t.Get(key) + return } // 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 +func (t *Table[K, V]) Has(key K) (exists bool) { + _, exists = t.Get(key) + return } // Put sets the value for a key. If it cannot be set, an error is returned, @@ -174,7 +190,7 @@ func (t *Table[K, V]) Put(key K, value V) (displaced Entry[K, V], err error) { // Drop removes a value for a key in the table. Returns whether the key had // existed. func (t *Table[K, V]) Drop(key K) bool { - occupied := t.bucketA.drop(key) || t.bucketB.drop(key) + occupied := t.tableA.drop(key) || t.tableB.drop(key) if t.load() < t.minLoadFactor { // The error is not handled here, because table-shrinking is an internal @@ -186,9 +202,9 @@ func (t *Table[K, V]) Drop(key K) bool { } // Entries returns an unordered sequence of all key-value pairs in the table. -func (t Table[K, V]) Entries() iter.Seq2[K, V] { +func (t *Table[K, V]) Entries() iter.Seq2[K, V] { return func(yield func(K, V) bool) { - for _, slot := range t.bucketA.slots { + for _, slot := range t.tableA.slots { if slot.occupied { if !yield(slot.Key, slot.Value) { return @@ -196,7 +212,7 @@ func (t Table[K, V]) Entries() iter.Seq2[K, V] { } } - for _, slot := range t.bucketB.slots { + for _, slot := range t.tableB.slots { if slot.occupied { if !yield(slot.Key, slot.Value) { return @@ -207,8 +223,8 @@ func (t Table[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 ...]". -func (t Table[K, V]) String() string { +// "table[k1:v1 k2:v2 ...]". +func (t *Table[K, V]) String() string { var sb strings.Builder sb.WriteString("table[") @@ -226,9 +242,9 @@ func (t Table[K, V]) String() string { return sb.String() } -// NewCustomTable creates a [Table] with custom [Hash] and [EqualFunc] +// NewCustom 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] { +func NewCustom[K, V any](hashA, hashB Hash[K], compare EqualFunc[K], options ...Option) *Table[K, V] { settings := &settings{ growthFactor: DefaultGrowthFactor, bucketSize: DefaultCapacity, @@ -242,8 +258,8 @@ func NewCustomTable[K, V any](hashA, hashB Hash[K], compare EqualFunc[K], option 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), + tableA: newSubtable[K, V](settings.bucketSize, hashA, compare), + tableB: newSubtable[K, V](settings.bucketSize, hashB, compare), } } @@ -251,10 +267,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 [Table] for any key type by using keyFunc to derive a +// 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 NewTableBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *Table[K, V] { - return NewCustomTable[K, V]( +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) }, @@ -262,10 +278,10 @@ func NewTableBy[K, V any, C comparable](keyFunc func(K) C, options ...Option) *T ) } -// NewTable creates a [Table] using the default [Hash] and [EqualFunc]. Use +// 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 -// [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...) +// [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...) }