README
¶
concurrent map 
As explained here and here, the map type in Go doesn't support concurrent reads and writes. concurrent-map provides a high-performance solution to this by sharding the map with minimal time spent waiting for locks.
Prior to Go 1.9, there was no concurrent map implementation in the stdlib. In Go 1.9, sync.Map was introduced. The new sync.Map has a few key differences from this map. The stdlib sync.Map is designed for append-only scenarios. So if you want to use the map for something more like in-memory db, you might benefit from using our version. You can read more about it in the golang repo, for example here and here
usage
Import the package:
import (
"github.com/orcaman/concurrent-map/v2"
)
go get "github.com/orcaman/concurrent-map/v2"
The package is now imported under the "cmap" namespace.
example
// Create a new map.
m := cmap.New[string]()
// Sets item within map, sets "bar" under key "foo"
m.Set("foo", "bar")
// Retrieve item from map.
bar, ok := m.Get("foo")
// Removes item under key "foo"
m.Remove("foo")
For more examples have a look at concurrent_map_test.go.
Running tests:
go test "github.com/orcaman/concurrent-map/v2"
guidelines for contributing
Contributions are highly welcome. In order for a contribution to be merged, please follow these guidelines:
- Open an issue and describe what you are after (fixing a bug, adding an enhancement, etc.).
- According to the core team's feedback on the above mentioned issue, submit a pull request, describing the changes and linking to the issue.
- New code must have test coverage.
- If the code is about performance issues, you must include benchmarks in the process (either in the issue or in the PR).
- In general, we would like to keep
concurrent-mapas simple as possible and as similar to the nativemap. Please keep this in mind when opening issues.
language
license
MIT (see LICENSE file)
Documentation
¶
Index ¶
- Variables
- type IterCb
- type MapShard
- type RemoveCb
- type Stringer
- type Tuple
- type UpsertCb
- type WeakMap
- func (m WeakMap[K, V]) Clear()
- func (m WeakMap[K, V]) Count() int
- func (m WeakMap[K, V]) Get(key K) (V, bool)
- func (m WeakMap[K, V]) GetShard(key K) *MapShard[K, V]
- func (m WeakMap[K, V]) Has(key K) bool
- func (m WeakMap[K, V]) IsEmpty() bool
- func (m WeakMap[K, V]) Items() map[K]V
- func (m WeakMap[K, V]) Iter() <-chan Tuple[K, V]deprecated
- func (m WeakMap[K, V]) IterBuffered() <-chan Tuple[K, V]
- func (m WeakMap[K, V]) IterCb(fn IterCb[K, V])
- func (m WeakMap[K, V]) Keys() []K
- func (m WeakMap[K, V]) MSet(data map[K]V)
- func (m WeakMap[K, V]) MarshalJSON() ([]byte, error)
- func (m WeakMap[K, V]) Pop(key K) (v V, exists bool)
- func (m WeakMap[K, V]) Remove(key K)
- func (m WeakMap[K, V]) RemoveCb(key K, cb RemoveCb[K, V]) bool
- func (m WeakMap[K, V]) Set(key K, value V)
- func (m WeakMap[K, V]) SetIfAbsent(key K, value V) bool
- func (m *WeakMap[K, V]) UnmarshalJSON(b []byte) (err error)
- func (m WeakMap[K, V]) Upsert(key K, value V, cb UpsertCb[V]) (res V)
Constants ¶
This section is empty.
Variables ¶
var SHARD_COUNT = 32
Functions ¶
This section is empty.
Types ¶
type IterCb ¶
type IterCb[K comparable, V any] func(key K, v V)
Iterator callbacalled for every key,value found in maps. RLock is held for all calls for a given shard therefore callback sess consistent view of a shard, but not across the shards
type MapShard ¶
type MapShard[K comparable, V any] struct { sync.Mutex // Read Write mutex, guards access to internal map. // contains filtered or unexported fields }
A "thread" safe string to anything map.
type RemoveCb ¶
RemoveCb is a callback executed in a map.RemoveCb() call, while Lock is held If returns true, the element will be removed from the map
type Stringer ¶
type Stringer interface {
fmt.Stringer
comparable
}
type Tuple ¶
type Tuple[K comparable, V any] struct { Key K Val V }
Used by the Iter & IterBuffered functions to wrap two variables together over a channel,
type UpsertCb ¶
Callback to return new element to be inserted into the map It is called while lock is held, therefore it MUST NOT try to access other keys in same map, as it can lead to deadlock since Go sync.RWLock is not reentrant
type WeakMap ¶
type WeakMap[K comparable, V any] struct { // contains filtered or unexported fields }
A "thread" safe map of type string:Anything. To avoid lock bottlenecks this map is dived to several (SHARD_COUNT) map shards.
func NewStringer ¶
Creates a new concurrent map.
func NewWithCustomShardingFunction ¶
func NewWithCustomShardingFunction[K comparable, V any](sharding func(key K) uint64) WeakMap[K, V]
Creates a new concurrent map.
func (WeakMap[K, V]) Items ¶
func (m WeakMap[K, V]) Items() map[K]V
Items returns all items as map[string]V
func (WeakMap[K, V]) IterBuffered ¶
IterBuffered returns a buffered iterator which could be used in a for range loop.
func (WeakMap[K, V]) MarshalJSON ¶
Reviles ConcurrentMap "private" variables to json marshal.
func (WeakMap[K, V]) Remove ¶
func (m WeakMap[K, V]) Remove(key K)
Remove removes an element from the map.
func (WeakMap[K, V]) RemoveCb ¶
RemoveCb locks the shard containing the key, retrieves its current value and calls the callback with those params If callback returns true and element exists, it will remove it from the map Returns the value returned by the callback (even if element was not present in the map)
func (WeakMap[K, V]) Set ¶
func (m WeakMap[K, V]) Set(key K, value V)
Sets the given value under the specified key.
func (WeakMap[K, V]) SetIfAbsent ¶
Sets the given value under the specified key if no value was associated with it.
func (*WeakMap[K, V]) UnmarshalJSON ¶
Reverse process of Marshal.
Source Files