README
¶
标准库 sync 扩展包
github.com/puzpuzpuz/xsync v20220407
注意: 仅 64 位构建通过了官方认证, 若要使用 32 位, 注意自己测试
xsync
Concurrent data structures for Go. An extension for the standard sync package.
This library should be considered experimental, so make sure to run tests and benchmarks for your use cases before adding it to your application.
Important note. Only 64-bit builds are officially supported at the moment. If you need to run a 32-bit build, make sure to test it and open a GH issue in case of any problems.
Benchmarks
Benchmark results may be found here.
Counter
A Counter is a striped int64 counter inspired by the j.u.c.a.LongAdder class from Java standard library.
var c xsync.Counter
// increment and decrement the counter
c.Inc()
c.Dec()
// read the current value
v := c.Value()
Works better in comparison with a single atomically updated int64 counter in high contention scenarios.
Map
A Map is like a concurrent hash table based map. It follows the interface of sync.Map.
m := xsync.NewMap()
m.Store("foo", "bar")
v, ok := m.Load("foo")
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.
MapOf[V] is an implementation with parametrized value type. It is available for Go 1.18 or later.
m := xsync.NewMapOf[string]()
m.Store("foo", "bar")
v, ok := m.Load("foo")
MPMCQueue
A MPMCQeueue is a bounded multi-producer multi-consumer concurrent queue.
q := xsync.NewMPMCQueue(1024)
// producer inserts an item into the queue
q.Enqueue("foo")
// optimistic insertion attempt; doesn't block
inserted := q.TryEnqueue("bar")
// consumer obtains an item from the queue
item := q.Dequeue()
// optimistic obtain attempt; doesn't block
item, ok := q.TryDequeue()
Based on the algorithm from the MPMCQueue C++ library which in its turn references D.Vyukov's MPMC queue. According to the following classification, the queue is array-based, fails on overflow, provides causal FIFO, has blocking producers and consumers.
The idea of the algorithm is to allow parallelism for concurrent producers and consumers by introducing the notion of tickets, i.e. values of two counters, one per producers/consumers. An atomic increment of one of those counters is the only noticeable contention point in queue operations. The rest of the operation avoids contention on writes thanks to the turn-based read/write access for each of the queue items.
In essence, MPMCQueue is a specialized queue for scenarios where there are multiple concurrent producers and consumers of a single queue running on a large multicore machine.
To get the optimal performance, you may want to set the queue size to be large enough, say, an order of magnitude greater than the number of producers/consumers, to allow producers and consumers to progress with their queue operations in parallel most of the time.
RBMutex
A RBMutex is a reader biased reader/writer mutual exclusion lock. The lock can be held by an many readers or a single writer.
var m xsync.RBMutex
// reader lock calls return a token
t := m.RLock()
// the token must be later used to unlock the mutex
m.RUnlock(t)
// writer locks are the same as in sync.RWMutex
m.Lock()
m.Unlock()
RBMutex is based on the BRAVO (Biased Locking for Reader-Writer Locks) algorithm: https://arxiv.org/pdf/1810.01553.pdf
The idea of the algorithm is to build on top of an existing reader-writer mutex and introduce a fast path for readers. On the fast path, reader lock attempts are sharded over an internal array based on the reader identity (a token in case of Golang). This means that readers do not contend over a single atomic counter like it's done in, say, sync.RWMutex allowing for better scalability in terms of cores.
Hence, by the design 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 should perform better than the 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 the reader tokens returned from the RLock/RUnlock methods.
License
Licensed under MIT.
Documentation
¶
Index ¶
- type Counter
- type MPMCQueue
- type Map
- 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) LoadOrStore(key string, value interface{}) (actual interface{}, loaded bool)
- func (m *Map) Range(f func(key string, value interface{}) bool)
- func (m *Map) Store(key string, value interface{})
- type MapOf
- func (m *MapOf[V]) Delete(key string)
- func (m *MapOf[V]) Load(key string) (value V, ok bool)
- func (m *MapOf[V]) LoadAndDelete(key string) (value V, loaded bool)
- func (m *MapOf[V]) LoadOrStore(key string, value V) (actual V, loaded bool)
- func (m *MapOf[V]) Range(f func(key string, value V) bool)
- func (m *MapOf[V]) Store(key string, value V)
- type RBMutex
- type RToken
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.
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 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.
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 (*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) 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. 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[V any] struct { // contains filtered or unexported fields }
MapOf is like a Go map[string]V but is safe for concurrent use by multiple goroutines without additional locking or coordination. It follows the interface of sync.Map.
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.
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 (*MapOf[V]) Load ¶ added in v0.4.3
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 (*MapOf[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[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[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. 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 the 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 the 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 (*RBMutex) Lock ¶
func (m *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 (m *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.
Source Files