Documentation
¶
Index ¶
- func WithGrowOnly() func(*MapConfig)
- func WithPresize(sizeHint int) func(*MapConfig)
- type Map
- func (m *Map) Clear()
- func (m *Map) Compute(key string, ...) (actual interface{}, ok bool)
- func (m *Map) Delete(key string)
- func (m *Map) Load(key string) (value interface{}, ok bool)
- func (m *Map) LoadAndDelete(key string) (value interface{}, loaded bool)
- func (m *Map) LoadAndStore(key string, value interface{}) (actual interface{}, loaded bool)
- func (m *Map) LoadOrCompute(key string, valueFn func() interface{}) (actual interface{}, loaded bool)
- func (m *Map) LoadOrStore(key string, value interface{}) (actual interface{}, loaded bool)
- func (m *Map) Range(f func(key string, value interface{}) bool)
- func (m *Map) Size() int
- func (m *Map) Stats() MapStats
- func (m *Map) Store(key string, value interface{})
- type MapConfig
- type MapOf
- func (m *MapOf[K, V]) Clear()
- func (m *MapOf[K, V]) Compute(key K, valueFn func(oldValue V, loaded bool) (newValue V, delete bool)) (actual V, ok bool)
- func (m *MapOf[K, V]) Delete(key K)
- func (m *MapOf[K, V]) Load(key K) (value V, ok bool)
- func (m *MapOf[K, V]) LoadAndDelete(key K) (value V, loaded bool)
- func (m *MapOf[K, V]) LoadAndStore(key K, value V) (actual V, loaded bool)
- func (m *MapOf[K, V]) LoadOrCompute(key K, valueFn func() V) (actual V, loaded bool)
- func (m *MapOf[K, V]) LoadOrStore(key K, value V) (actual V, loaded bool)
- func (m *MapOf[K, V]) Range(f func(key K, value V) bool)
- func (m *MapOf[K, V]) Size() int
- func (m *MapOf[K, V]) Stats() MapStats
- func (m *MapOf[K, V]) Store(key K, value V)
- type MapStats
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func WithGrowOnly ¶ added in v0.3.1
func WithGrowOnly() func(*MapConfig)
WithGrowOnly configures new Map/MapOf instance to be grow-only. This means that the underlying hash table grows in capacity when new keys are added, but does not shrink when keys are deleted. The only exception to this rule is the Clear method which shrinks the hash table back to the initial capacity.
func WithPresize ¶ added in v0.3.1
WithPresize configures new Map/MapOf instance with capacity enough to hold sizeHint entries. The capacity is treated as the minimal capacity meaning that the underlying hash table will never shrink to a smaller capacity. If sizeHint is zero or negative, the value is ignored.
Types ¶
type Map ¶
type Map struct {
// contains filtered or unexported fields
}
Map is like a Go map[string]interface{} but is safe for concurrent use by multiple goroutines without additional locking or coordination. It follows the interface of sync.Map with a number of valuable extensions like Compute or Size.
A Map must not be copied after first use.
Map uses a modified version of Cache-Line Hash Table (CLHT) data structure: https://github.com/LPD-EPFL/CLHT
CLHT is built around idea to organize the hash table in cache-line-sized buckets, so that on all modern CPUs update operations complete with at most one cache-line transfer. Also, Get operations involve no write to memory, as well as no mutexes or any other sort of locks. Due to this design, in all considered scenarios Map outperforms sync.Map.
One important difference with sync.Map is that only string keys are supported. That's because Golang standard library does not expose the built-in hash functions for interface{} values.
func NewMapPresized
deprecated
added in
v0.1.3
NewMapPresized creates a new Map instance with capacity enough to hold sizeHint entries. The capacity is treated as the minimal capacity meaning that the underlying hash table will never shrink to a smaller capacity. If sizeHint is zero or negative, the value is ignored.
Deprecated: use NewMap in combination with WithPresize.
func (*Map) Clear ¶ added in v0.1.0
func (m *Map) Clear()
Clear deletes all keys and values currently stored in the map.
func (*Map) Compute ¶ added in v0.1.0
func (m *Map) Compute( key string, valueFn func(oldValue interface{}, loaded bool) (newValue interface{}, delete bool), ) (actual interface{}, ok bool)
Compute either sets the computed new value for the key or deletes the value for the key. When the delete result of the valueFn function is set to true, the value will be deleted, if it exists. When delete is set to false, the value is updated to the newValue. The ok result indicates whether value was computed and stored, thus, is present in the map. The actual result contains the new value in cases where the value was computed and stored. See the example for a few use cases.
This call locks a hash table bucket while the compute function is executed. It means that modifications on other entries in the bucket will be blocked until the valueFn executes. Consider this when the function includes long-running operations.
func (*Map) Load ¶
Load returns the value stored in the map for a key, or nil if no value is present. The ok result indicates whether value was found in the map.
func (*Map) LoadAndDelete ¶
LoadAndDelete deletes the value for a key, returning the previous value if any. The loaded result reports whether the key was present.
func (*Map) LoadAndStore ¶
LoadAndStore returns the existing value for the key if present, while setting the new value for the key. It stores the new value and returns the existing one, if present. The loaded result is true if the existing value was loaded, false otherwise.
func (*Map) LoadOrCompute ¶ added in v0.1.0
func (m *Map) LoadOrCompute(key string, valueFn func() interface{}) (actual interface{}, loaded bool)
LoadOrCompute returns the existing value for the key if present. Otherwise, it computes the value using the provided function and returns the computed value. The loaded result is true if the value was loaded, false if stored.
This call locks a hash table bucket while the compute function is executed. It means that modifications on other entries in the bucket will be blocked until the valueFn executes. Consider this when the function includes long-running operations.
func (*Map) LoadOrStore ¶
LoadOrStore returns the existing value for the key if present. Otherwise, it stores and returns the given value. The loaded result is true if the value was loaded, false if stored.
func (*Map) Range ¶
Range calls f sequentially for each key and value present in the map. If f returns false, range stops the iteration.
Range does not necessarily correspond to any consistent snapshot of the Map's contents: no key will be visited more than once, but if the value for any key is stored or deleted concurrently, Range may reflect any mapping for that key from any point during the Range call.
It is safe to modify the map while iterating it, including entry creation, modification and deletion. However, the concurrent modification rule apply, i.e. the changes may be not reflected in the subsequently iterated entries.
type MapConfig ¶ added in v0.3.1
type MapConfig struct {
// contains filtered or unexported fields
}
MapConfig defines configurable Map/MapOf options.
type MapOf ¶
type MapOf[K comparable, V any] struct { // contains filtered or unexported fields }
MapOf is like a Go map[K]V but is safe for concurrent use by multiple goroutines without additional locking or coordination. It follows the interface of sync.Map with a number of valuable extensions like Compute or Size.
A MapOf must not be copied after first use.
MapOf uses a modified version of Cache-Line Hash Table (CLHT) data structure: https://github.com/LPD-EPFL/CLHT
CLHT is built around idea to organize the hash table in cache-line-sized buckets, so that on all modern CPUs update operations complete with at most one cache-line transfer. Also, Get operations involve no write to memory, as well as no mutexes or any other sort of locks. Due to this design, in all considered scenarios MapOf outperforms sync.Map.
MapOf also borrows ideas from Java's j.u.c.ConcurrentHashMap (immutable K/V pair structs instead of atomic snapshots) and C++'s absl::flat_hash_map (meta memory and SWAR-based lookups).
func NewMapOf ¶
func NewMapOf[K comparable, V any](options ...func(*MapConfig)) *MapOf[K, V]
NewMapOf creates a new MapOf instance configured with the given options.
func NewMapOfPresized
deprecated
added in
v0.1.3
func NewMapOfPresized[K comparable, V any](sizeHint int) *MapOf[K, V]
NewMapOfPresized creates a new MapOf instance with capacity enough to hold sizeHint entries. The capacity is treated as the minimal capacity meaning that the underlying hash table will never shrink to a smaller capacity. If sizeHint is zero or negative, the value is ignored.
Deprecated: use NewMapOf in combination with WithPresize.
func NewMapOfWithHasher ¶ added in v0.3.1
func NewMapOfWithHasher[K comparable, V any]( hasher func(K, uint64) uint64, options ...func(*MapConfig), ) *MapOf[K, V]
NewMapOfWithHasher creates a new MapOf instance configured with the given hasher and options. The hash function is used instead of the built-in hash function configured when a map is created with the NewMapOf function.
func (*MapOf[K, V]) Clear ¶ added in v0.1.0
func (m *MapOf[K, V]) Clear()
Clear deletes all keys and values currently stored in the map.
func (*MapOf[K, V]) Compute ¶ added in v0.1.0
func (m *MapOf[K, V]) Compute( key K, valueFn func(oldValue V, loaded bool) (newValue V, delete bool), ) (actual V, ok bool)
Compute either sets the computed new value for the key or deletes the value for the key. When the delete result of the valueFn function is set to true, the value will be deleted, if it exists. When delete is set to false, the value is updated to the newValue. The ok result indicates whether value was computed and stored, thus, is present in the map. The actual result contains the new value in cases where the value was computed and stored. See the example for a few use cases.
This call locks a hash table bucket while the compute function is executed. It means that modifications on other entries in the bucket will be blocked until the valueFn executes. Consider this when the function includes long-running operations.
func (*MapOf[K, V]) Delete ¶
func (m *MapOf[K, V]) Delete(key K)
Delete deletes the value for a key.
func (*MapOf[K, V]) Load ¶
Load returns the value stored in the map for a key, or zero value of type V if no value is present. The ok result indicates whether value was found in the map.
func (*MapOf[K, V]) LoadAndDelete ¶
LoadAndDelete deletes the value for a key, returning the previous value if any. The loaded result reports whether the key was present.
func (*MapOf[K, V]) LoadAndStore ¶
LoadAndStore returns the existing value for the key if present, while setting the new value for the key. It stores the new value and returns the existing one, if present. The loaded result is true if the existing value was loaded, false otherwise.
func (*MapOf[K, V]) LoadOrCompute ¶ added in v0.1.0
LoadOrCompute returns the existing value for the key if present. Otherwise, it computes the value using the provided function and returns the computed value. The loaded result is true if the value was loaded, false if stored.
This call locks a hash table bucket while the compute function is executed. It means that modifications on other entries in the bucket will be blocked until the valueFn executes. Consider this when the function includes long-running operations.
func (*MapOf[K, V]) LoadOrStore ¶
LoadOrStore returns the existing value for the key if present. Otherwise, it stores and returns the given value. The loaded result is true if the value was loaded, false if stored.
func (*MapOf[K, V]) Range ¶
Range calls f sequentially for each key and value present in the map. If f returns false, range stops the iteration.
Range does not necessarily correspond to any consistent snapshot of the Map's contents: no key will be visited more than once, but if the value for any key is stored or deleted concurrently, Range may reflect any mapping for that key from any point during the Range call.
It is safe to modify the map while iterating it, including entry creation, modification and deletion. However, the concurrent modification rule apply, i.e. the changes may be not reflected in the subsequently iterated entries.
type MapStats ¶ added in v0.3.1
type MapStats struct {
// RootBuckets is the number of root buckets in the hash table.
// Each bucket holds a few entries.
RootBuckets int
// TotalBuckets is the total number of buckets in the hash table,
// including root and their chained buckets. Each bucket holds
// a few entries.
TotalBuckets int
// EmptyBuckets is the number of buckets that hold no entries.
EmptyBuckets int
// Capacity is the Map/MapOf capacity, i.e. the total number of
// entries that all buckets can physically hold. This number
// does not consider the load factor.
Capacity int
// Size is the exact number of entries stored in the map.
Size int
// Counter is the number of entries stored in the map according
// to the internal atomic counter. In case of concurrent map
// modifications this number may be different from Size.
Counter int
// CounterLen is the number of internal atomic counter stripes.
// This number may grow with the map capacity to improve
// multithreaded scalability.
CounterLen int
// MinEntries is the minimum number of entries per a chain of
// buckets, i.e. a root bucket and its chained buckets.
MinEntries int
// MinEntries is the maximum number of entries per a chain of
// buckets, i.e. a root bucket and its chained buckets.
MaxEntries int
// TotalGrowths is the number of times the hash table grew.
TotalGrowths int64
// TotalGrowths is the number of times the hash table shrinked.
TotalShrinks int64
}
MapStats is Map/MapOf statistics.
Warning: map statistics are intented to be used for diagnostic purposes, not for production code. This means that breaking changes may be introduced into this struct even between minor releases.
Source Files