Documentation ¶
Index ¶
- type Counter
- type HashMapOf
- type MPMCQueue
- type MPMCQueueOf
- 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) Store(key string, value interface{})
- 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]) Store(key K, value V)
- type RBMutex
- type RToken
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Counter ¶
type Counter struct {
// contains filtered or unexported fields
}
A Counter is a striped int64 counter.
Should be preferred over a single atomically updated int64 counter in high contention scenarios.
A Counter must not be copied after first use.
func NewCounter ¶ added in v0.8.2
func NewCounter() *Counter
NewCounter creates a new Counter instance.
type HashMapOf ¶ added in v0.8.0
type HashMapOf[K comparable, V any] interface { // 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. Load(key K) (value V, ok bool) // Store sets the value for a key. Store(key K, value V) // 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. LoadOrStore(key K, value V) (actual V, loaded bool) // 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. LoadAndStore(key K, value V) (actual V, 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. LoadOrCompute(key K, valueFn func() V) (actual V, loaded 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. Compute( key K, valueFn func(oldValue V, loaded bool) (newValue V, delete bool), ) (actual V, ok bool) // LoadAndDelete deletes the value for a key, returning the previous // value if any. The loaded result reports whether the key was // present. LoadAndDelete(key K) (value V, loaded bool) // Delete deletes the value for a key. Delete(key K) // 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. However, the // concurrent modification rule apply, i.e. the changes may be not // reflected in the subsequently iterated entries. Range(f func(key K, value V) bool) // Clear deletes all keys and values currently stored in the map. Clear() // Size returns current size of the map. Size() int }
type MPMCQueue ¶
type MPMCQueue struct {
// contains filtered or unexported fields
}
A MPMCQueue is a bounded multi-producer multi-consumer concurrent queue.
MPMCQueue instances must be created with NewMPMCQueue function. A MPMCQueue must not be copied after first use.
Based on the data structure from the following C++ library: https://github.com/rigtorp/MPMCQueue
func NewMPMCQueue ¶
NewMPMCQueue creates a new MPMCQueue instance with the given capacity.
func (*MPMCQueue) Dequeue ¶
func (q *MPMCQueue) Dequeue() interface{}
Dequeue retrieves and removes the item from the head of the queue. Blocks, if the queue is empty.
func (*MPMCQueue) Enqueue ¶
func (q *MPMCQueue) Enqueue(item interface{})
Enqueue inserts the given item into the queue. Blocks, if the queue is full.
func (*MPMCQueue) TryDequeue ¶
TryDequeue retrieves and removes the item from the head of the queue. Does not block and returns immediately. The ok result indicates that the queue isn't empty and an item was retrieved.
func (*MPMCQueue) TryEnqueue ¶
TryEnqueue inserts the given item into the queue. Does not block and returns immediately. The result indicates that the queue isn't full and the item was inserted.
type MPMCQueueOf ¶ added in v0.11.1
type MPMCQueueOf[I any] struct { // contains filtered or unexported fields }
A MPMCQueueOf is a bounded multi-producer multi-consumer concurrent queue. It's a generic version of MPMCQueue.
MPMCQueue instances must be created with NewMPMCQueueOf function. A MPMCQueueOf must not be copied after first use.
Based on the data structure from the following C++ library: https://github.com/rigtorp/MPMCQueue
func NewMPMCQueueOf ¶ added in v0.11.1
func NewMPMCQueueOf[I any](capacity int) *MPMCQueueOf[I]
NewMPMCQueueOf creates a new MPMCQueueOf instance with the given capacity.
func (*MPMCQueueOf[I]) Dequeue ¶ added in v0.11.1
func (q *MPMCQueueOf[I]) Dequeue() I
Dequeue retrieves and removes the item from the head of the queue. Blocks, if the queue is empty.
func (*MPMCQueueOf[I]) Enqueue ¶ added in v0.11.1
func (q *MPMCQueueOf[I]) Enqueue(item I)
Enqueue inserts the given item into the queue. Blocks, if the queue is full.
func (*MPMCQueueOf[I]) TryDequeue ¶ added in v0.11.1
func (q *MPMCQueueOf[I]) TryDequeue() (item I, ok bool)
TryDequeue retrieves and removes the item from the head of the queue. Does not block and returns immediately. The ok result indicates that the queue isn't empty and an item was retrieved.
func (*MPMCQueueOf[I]) TryEnqueue ¶ added in v0.11.1
func (q *MPMCQueueOf[I]) TryEnqueue(item I) bool
TryEnqueue inserts the given item into the queue. Does not block and returns immediately. The result indicates that the queue isn't full and the item was inserted.
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 ¶ added in v0.9.0
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.
func (*Map) Clear ¶ added in v0.8.2
func (m *Map) Clear()
Clear deletes all keys and values currently stored in the map.
func (*Map) Compute ¶ added in v0.8.2
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 ¶ added in v0.7.5
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.7.18
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 MapOf ¶ added in v0.4.3
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.
func NewMapOf ¶ added in v0.4.3
func NewMapOf[K comparable, V any]() *MapOf[K, V]
NewMapOf creates a new MapOf instance.
func NewMapOfPresized ¶ added in v0.9.0
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.
func (*MapOf[K, V]) Clear ¶ added in v0.8.2
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.8.2
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.
Example ¶
package main import ( "errors" "fmt" "github.com/fufuok/utils/xsync" ) func main() { counts := xsync.NewMapOf[int, int]() // Store a new value. v, ok := counts.Compute(42, func(oldValue int, loaded bool) (newValue int, delete bool) { // loaded is false here. newValue = 42 delete = false return }) // v: 42, ok: true fmt.Printf("v: %v, ok: %v\n", v, ok) // Update an existing value. v, ok = counts.Compute(42, func(oldValue int, loaded bool) (newValue int, delete bool) { // loaded is true here. newValue = oldValue + 42 delete = false return }) // v: 84, ok: true fmt.Printf("v: %v, ok: %v\n", v, ok) // Set a new value or keep the old value conditionally. var oldVal int minVal := 63 v, ok = counts.Compute(42, func(oldValue int, loaded bool) (newValue int, delete bool) { oldVal = oldValue if !loaded || oldValue < minVal { newValue = minVal delete = false return } newValue = oldValue delete = false return }) // v: 84, ok: true, oldVal: 84 fmt.Printf("v: %v, ok: %v, oldVal: %v\n", v, ok, oldVal) // Delete an existing value. v, ok = counts.Compute(42, func(oldValue int, loaded bool) (newValue int, delete bool) { // loaded is true here. delete = true return }) // v: 84, ok: false fmt.Printf("v: %v, ok: %v\n", v, ok) // Propagate an error from the compute function to the outer scope. var err error v, ok = counts.Compute(42, func(oldValue int, loaded bool) (newValue int, delete bool) { if oldValue == 42 { err = errors.New("something went wrong") return 0, true // no need to create a key/value pair } newValue = 0 delete = false return }) fmt.Printf("err: %v\n", err) }
Output:
func (*MapOf[K, V]) Delete ¶ added in v0.4.3
func (m *MapOf[K, V]) Delete(key K)
Delete deletes the value for a key.
func (*MapOf[K, V]) Load ¶ added in v0.4.3
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 ¶ added in v0.4.3
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 ¶ added in v0.7.5
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.7.18
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 ¶ added in v0.4.3
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 ¶ added in v0.4.3
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 RBMutex ¶
type RBMutex struct {
// contains filtered or unexported fields
}
A RBMutex is a reader biased reader/writer mutual exclusion lock. The lock can be held by an many readers or a single writer. The zero value for a RBMutex is an unlocked mutex.
A RBMutex must not be copied after first use.
RBMutex is based on a modified version of BRAVO (Biased Locking for Reader-Writer Locks) algorithm: https://arxiv.org/pdf/1810.01553.pdf
RBMutex is a specialized mutex for scenarios, such as caches, where the vast majority of locks are acquired by readers and write lock acquire attempts are infrequent. In such scenarios, RBMutex performs better than sync.RWMutex on large multicore machines.
RBMutex extends sync.RWMutex internally and uses it as the "reader bias disabled" fallback, so the same semantics apply. The only noticeable difference is in reader tokens returned from the RLock/RUnlock methods.
func NewRBMutex ¶ added in v0.8.3
func NewRBMutex() *RBMutex
NewRBMutex creates a new RBMutex instance.
func (*RBMutex) Lock ¶
func (mu *RBMutex) Lock()
Lock locks m for writing. If the lock is already locked for reading or writing, Lock blocks until the lock is available.
func (*RBMutex) RLock ¶
RLock locks m for reading and returns a reader token. The token must be used in the later RUnlock call.
Should not be used for recursive read locking; a blocked Lock call excludes new readers from acquiring the lock.
func (*RBMutex) RUnlock ¶
RUnlock undoes a single RLock call. A reader token obtained from the RLock call must be provided. RUnlock does not affect other simultaneous readers. A panic is raised if m is not locked for reading on entry to RUnlock.
func (*RBMutex) Unlock ¶
func (mu *RBMutex) Unlock()
Unlock unlocks m for writing. A panic is raised if m is not locked for writing on entry to Unlock.
As with RWMutex, a locked RBMutex is not associated with a particular goroutine. One goroutine may RLock (Lock) a RBMutex and then arrange for another goroutine to RUnlock (Unlock) it.