go-cuckoo/settings.go

package cuckoo

import "fmt"

// 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 [Table]. Most
// hash table 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
// succeed. The value of 5% is taken from [libcuckoo].
//
// [libcuckoo]: https://github.com/efficient/libcuckoo/blob/656714705a055df2b7a605eb3c71586d9da1e119/libcuckoo/cuckoohash_config.hh#L21
const defaultMinimumLoad float64 = 0.05

type settings struct {
	growthFactor  uint64
	minLoadFactor float64
	bucketSize    uint64
}

// An Option modifies the settings of a [Table]. It is used in its constructors
// like [NewTable], for example.
type Option func(*settings)

// Capacity modifies the starting capacity of each bucket of the [Table]. The
// value must be non-negative.
func Capacity(value int) Option {
	if value < 0 {
		panic(fmt.Sprintf("go-cuckoo: Capacity must be non-negative, got %d", value))
	}

	return func(s *settings) { s.bucketSize = uint64(value) }
}

// 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 {
		panic(fmt.Sprintf("go-cuckoo: GrowthFactor must be greater than 1, got %d", value))
	}

	return func(s *settings) { s.growthFactor = uint64(value) }
}