go-cuckoo/table.go

package cuckoo

import (
	"errors"
	"fmt"
	"iter"
	"math/bits"
	"strings"
)

// ErrBadHash occurs when the hashes given to a [Table] cause too many key
// collisions. Discard the old table, rebuild it from your source data, and try:
//
//  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
}

// 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
}

// 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)
}

func log2(n uint64) (m int) {
	return max(0, bits.Len64(n)-1)
}

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
	}

	return float64(t.Size()) / float64(t.TotalCapacity())
}

// insert attempts to put/update an entry in the table, without modifying the
// 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.tableA.update(entry.key, entry.value) {
		return
	}

	if t.tableB.update(entry.key, entry.value) {
		return
	}

	for range t.maxEvictions() {
		if entry, homeless = t.tableA.insert(entry); !homeless {
			return
		}

		if entry, homeless = t.tableB.insert(entry); !homeless {
			return
		}
	}

	return entry, true
}

// 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]{
		growthFactor:  t.growthFactor,
		minLoadFactor: t.minLoadFactor,
		tableA:        t.tableA.resized(capacity),
		tableB:        t.tableB.resized(capacity),
	}
}

// resize creates a new [Table.resized] with 'capacity', inserts all items into
// the array, and replaces the current table. It is a helper function for
// [Table.grow] and [Table.shrink]; use them instead.
func (t *Table[K, V]) resize(capacity uint64) bool {
	updated := t.resized(capacity)

	for k, v := range t.Entries() {
		if _, failed := updated.insert(entry[K, V]{k, v}); failed {
			return false
		}
	}

	*t = *updated
	return true
}

// 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

	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 *Table[K, V]) shrink() bool {
	return t.resize(t.tableA.capacity / t.growthFactor)
}

// 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.tableB.get(key); ok {
		return item, true
	}

	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) {
	_, exists = t.Get(key)
	return
}

// Put sets the value for a key. If it cannot be set, an error is returned.
func (t *Table[K, V]) Put(key K, value V) (err error) {
	var (
		entry    = entry[K, V]{key, value}
		homeless bool
	)

	for range defaultGrowthLimit {
		if entry, homeless = t.insert(entry); !homeless {
			return
		}

		// Both this and the growth limit are necessary: this catches bad hashes
		// early when the table is sparse, while the latter catches cases where
		// growing never helps.
		if t.load() < t.minLoadFactor {
			return fmt.Errorf("hash functions produced a cycle at load %d/%d: %w", t.Size(), t.TotalCapacity(), ErrBadHash)
		}

		// It is theoretically possible to have a table with a larger capacity
		// that is valid. But this chance is astronomically small, so we ignore
		// it in this implementation.
		if grew := t.grow(); !grew {
			return fmt.Errorf("could not redistribute entries into larger table: %w", ErrBadHash)
		}
	}

	return fmt.Errorf("could not place entry after %d resizes: %w", defaultGrowthLimit, ErrBadHash)
}

// 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.tableA.drop(key) || t.tableB.drop(key)

	if t.load() < t.minLoadFactor {
		// The error is not handled here, because table-shrinking is an internal
		// optimization.
		t.shrink()
	}

	return occupied
}

// 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...)
}