README
¶
🌈 Concurrent Map
sync.Map with better read and write performance (supports any type of the key)
forked from orcaman/concurrent-map
For cache, you can choose: Cache/CacheOf and Map/MapOf
✨ Changelog
- Unified initialization method:
cmap.NewOf[K, V](), Usedxxhash, thanks. - For generics: Optionally specify the number of shards to improve performance.
func NewOf[K Hashable, V any](numShards ...int) *MapOf[K, V]
- Supports both generic and non-generic types.
- Add benchmarks for commonly used Map packages, See: 🤖 Benchmarks
🔖 Tips
ShardCount can also be specified globally, but it must be executed before all Maps are initialized and cannot be modified.
cmap.ShardCount = 128
⚙️ Installation
go get -u github.com/fufuok/cmap
⚡️ Quickstart
non-generic
package main
import (
"fmt"
"github.com/fufuok/cmap"
)
func main() {
m := cmap.New()
m.Set("A", 1)
v := m.Upsert("A", 2, func(exist bool, valueInMap interface{}, newValue interface{}) interface{} {
if valueInMap == 1 {
return newValue.(int) + 1
}
return 0
})
fmt.Println(v)
fmt.Println(m.Get("A"))
m.SetIfAbsent("B", 42)
m.Remove("A")
fmt.Println(m.Count())
for item := range m.IterBuffered() {
fmt.Println(item)
}
m.Clear()
// Output:
// 3
// 3 true
// 1
// {B 42}
}
generic
package main
import (
"fmt"
"github.com/fufuok/cmap"
)
func main() {
// Specifies the number of shards.
// m := cmap.NewOf[int, int](128)
m := cmap.NewOf[int, int]()
m.Set(1, 1)
v := m.Upsert(1, 2, func(exist bool, valueInMap int, newValue int) int {
if valueInMap == 1 {
return newValue + 1
}
return 0
})
fmt.Println(v)
fmt.Println(m.Get(1))
m.SetIfAbsent(2, 42)
m.Remove(1)
fmt.Println(m.Count())
for item := range m.IterBuffered() {
fmt.Println(item)
}
m.Clear()
// Output:
// 3
// 3 true
// 1
// {2 42}
}
custom type
package main
import (
"fmt"
"github.com/fufuok/cmap"
)
type Person struct {
name string
age int16
}
func main() {
hasher := func(p Person) uint64 {
return uint64(fnv32(p.name))<<32 | uint64(31*p.age)
}
m := cmap.NewTypedMapOf[Person, int](hasher)
m.Set(Person{"ff", 18}, 1)
v := m.Upsert(Person{"ff", 18}, 2, func(exist bool, valueInMap int, newValue int) int {
if valueInMap == 1 {
return newValue + 1
}
return 0
})
fmt.Println(v)
fmt.Println(m.Get(Person{"ff", 18}))
m.SetIfAbsent(Person{"uu", 20}, 42)
m.Remove(Person{"ff", 18})
fmt.Println(m.Count())
for item := range m.IterBuffered() {
fmt.Println(item)
}
m.Clear()
// Output:
// 3
// 3 true
// 1
// {{uu 20} 42}
}
func fnv32(key string) uint32 {
hash := uint32(2166136261)
const prime32 = uint32(16777619)
keyLength := len(key)
for i := 0; i < keyLength; i++ {
hash *= prime32
hash ^= uint32(key[i])
}
return hash
}
LICENSE
MIT (see LICENSE file)
ff
Documentation
¶
Index ¶
- Variables
- type Hashable
- type IterCb
- type IterCbOf
- type Map
- func (m Map) Clear()
- func (m Map) Count() int
- func (m Map) Get(key string) (interface{}, bool)
- func (m Map) GetShard(key string) *Shared
- func (m Map) GetValue(key string) (val interface{})
- func (m Map) Has(key string) bool
- func (m Map) IsEmpty() bool
- func (m Map) Items() map[string]interface{}
- func (m Map) IterBuffered() <-chan Tuple
- func (m Map) IterCb(fn IterCb)
- func (m Map) Keys() []string
- func (m Map) MSet(data map[string]interface{})
- func (m Map) MarshalJSON() ([]byte, error)
- func (m Map) Pop(key string) (v interface{}, exists bool)
- func (m Map) Remove(key string)
- func (m Map) RemoveCb(key string, cb RemoveCb) bool
- func (m Map) Set(key string, value interface{})
- func (m Map) SetIfAbsent(key string, value interface{}) bool
- func (m Map) Upsert(key string, value interface{}, cb UpsertCb) (res interface{})
- type MapOf
- func (m *MapOf[K, V]) Clear()
- func (m *MapOf[K, V]) Count() int
- func (m *MapOf[K, V]) Get(key K) (V, bool)
- func (m *MapOf[K, V]) GetShard(key K) *SharedOf[K, V]
- func (m *MapOf[K, V]) GetValue(key K) (val V)
- func (m *MapOf[K, V]) Has(key K) bool
- func (m *MapOf[K, V]) IsEmpty() bool
- func (m *MapOf[K, V]) Items() map[K]V
- func (m *MapOf[K, V]) IterBuffered() <-chan TupleOf[K, V]
- func (m *MapOf[K, V]) IterCb(fn IterCbOf[K, V])
- func (m *MapOf[K, V]) Keys() []K
- func (m *MapOf[K, V]) MSet(data map[K]V)
- func (m *MapOf[K, V]) MarshalJSON() ([]byte, error)
- func (m *MapOf[K, V]) Pop(key K) (v V, exists bool)
- func (m *MapOf[K, V]) Remove(key K)
- func (m *MapOf[K, V]) RemoveCb(key K, cb RemoveCbOf[K, V]) bool
- func (m *MapOf[K, V]) Set(key K, value V)
- func (m *MapOf[K, V]) SetIfAbsent(key K, value V) bool
- func (m *MapOf[K, V]) UnmarshalJSON(b []byte) (err error)
- func (m *MapOf[K, V]) Upsert(key K, value V, cb UpsertCbOf[V]) (res V)
- type RemoveCb
- type RemoveCbOf
- type Shared
- type SharedOf
- type Tuple
- type TupleOf
- type UpsertCb
- type UpsertCbOf
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ShardCount = 32
Functions ¶
This section is empty.
Types ¶
type Hashable ¶ added in v1.19.1
type Hashable interface {
~int | ~int8 | ~int16 | ~int32 | ~int64 | ~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr |
~float32 | ~float64 | ~string | ~complex64 | ~complex128
}
Hashable allowed map key types constraint
type IterCb ¶
type IterCb func(key string, v interface{})
IterCb iterator callback,called 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 IterCbOf ¶ added in v1.19.0
type IterCbOf[K comparable, V any] func(key K, v V)
IterCbOf 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 Map ¶ added in v1.19.0
type Map []*Shared
Map a "thread" safe map of type string:Anything. To avoid lock bottlenecks this map is dived to several (ShardCount) map shards.
Example ¶
package main
import (
"fmt"
"github.com/fufuok/cmap"
)
func main() {
m := cmap.New()
m.Set("A", 1)
v := m.Upsert("A", 2, func(exist bool, valueInMap interface{}, newValue interface{}) interface{} {
if valueInMap == 1 {
return newValue.(int) + 1
}
return 0
})
fmt.Println(v)
fmt.Println(m.Get("A"))
m.SetIfAbsent("B", 42)
m.Remove("A")
fmt.Println(m.Count())
for item := range m.IterBuffered() {
fmt.Println(item)
}
m.Clear()
}
Output: 3 3 true 1 {B 42}
func (Map) IterBuffered ¶ added in v1.19.0
IterBuffered returns a buffered iterator which could be used in a for range loop.
func (Map) IterCb ¶ added in v1.19.0
IterCb callback based iterator, cheapest way to read all elements in a map.
func (Map) MarshalJSON ¶ added in v1.19.0
MarshalJSON reviles Map "private" variables to json marshal.
func (Map) RemoveCb ¶ added in v1.19.0
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 (Map) SetIfAbsent ¶ added in v1.19.0
SetIfAbsent sets the given value under the specified key if no value was associated with it.
type MapOf ¶ added in v1.19.0
type MapOf[K comparable, V any] struct { // contains filtered or unexported fields }
MapOf a "thread" safe map of type comparable:Anything. To avoid lock bottlenecks this map is dived to several (ShardCount) map shards.
func NewOf ¶ added in v1.19.0
NewOf creates a new concurrent map, optionally specify the number of shards.
Example ¶
package main
import (
"fmt"
"github.com/fufuok/cmap"
)
func main() {
m := cmap.NewOf[int, int]()
m.Set(1, 1)
v := m.Upsert(1, 2, func(exist bool, valueInMap int, newValue int) int {
if valueInMap == 1 {
return newValue + 1
}
return 0
})
fmt.Println(v)
fmt.Println(m.Get(1))
m.SetIfAbsent(2, 42)
m.Remove(1)
fmt.Println(m.Count())
for item := range m.IterBuffered() {
fmt.Println(item)
}
m.Clear()
}
Output: 3 3 true 1 {2 42}
func NewTypedMapOf ¶ added in v1.19.1
func NewTypedMapOf[K comparable, V any](sharding func(key K) uint64, numShards ...int) *MapOf[K, V]
NewTypedMapOf creates a new concurrent map, optionally specify the number of shards.
Example ¶
package main
import (
"fmt"
"github.com/fufuok/cmap"
)
type Person struct {
name string
age int16
}
func main() {
hasher := func(p Person) uint64 {
return uint64(fnv32(p.name))<<32 | uint64(31*p.age)
}
m := cmap.NewTypedMapOf[Person, int](hasher)
m.Set(Person{"ff", 18}, 1)
v := m.Upsert(Person{"ff", 18}, 2, func(exist bool, valueInMap int, newValue int) int {
if valueInMap == 1 {
return newValue + 1
}
return 0
})
fmt.Println(v)
fmt.Println(m.Get(Person{"ff", 18}))
m.SetIfAbsent(Person{"uu", 20}, 42)
m.Remove(Person{"ff", 18})
fmt.Println(m.Count())
for item := range m.IterBuffered() {
fmt.Println(item)
}
m.Clear()
}
func fnv32(key string) uint32 {
hash := uint32(2166136261)
const prime32 = uint32(16777619)
keyLength := len(key)
for i := 0; i < keyLength; i++ {
hash *= prime32
hash ^= uint32(key[i])
}
return hash
}
Output: 3 3 true 1 {{uu 20} 42}
func (*MapOf[K, V]) Clear ¶ added in v1.19.0
func (m *MapOf[K, V]) Clear()
Clear removes all items from map.
func (*MapOf[K, V]) GetValue ¶ added in v1.19.3
func (m *MapOf[K, V]) GetValue(key K) (val V)
GetValue get retrieves an element from map under given key.
func (*MapOf[K, V]) Items ¶ added in v1.19.0
func (m *MapOf[K, V]) Items() map[K]V
Items returns all items as map[string]V
func (*MapOf[K, V]) IterBuffered ¶ added in v1.19.0
IterBuffered returns a buffered iterator which could be used in a for range loop.
func (*MapOf[K, V]) IterCb ¶ added in v1.19.0
IterCb Callback based iterator, cheapest way to read all elements in a map.
func (*MapOf[K, V]) Keys ¶ added in v1.19.0
func (m *MapOf[K, V]) Keys() []K
Keys returns all keys as []string
func (*MapOf[K, V]) MarshalJSON ¶ added in v1.19.0
MarshalJSON reviles MapOf "private" variables to json marshal.
func (*MapOf[K, V]) Remove ¶ added in v1.19.0
func (m *MapOf[K, V]) Remove(key K)
Remove removes an element from the map.
func (*MapOf[K, V]) RemoveCb ¶ added in v1.19.0
func (m *MapOf[K, V]) RemoveCb(key K, cb RemoveCbOf[K, V]) bool
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 (*MapOf[K, V]) Set ¶ added in v1.19.0
func (m *MapOf[K, V]) Set(key K, value V)
Set sets the given value under the specified key.
func (*MapOf[K, V]) SetIfAbsent ¶ added in v1.19.0
SetIfAbsent sets the given value under the specified key if no value was associated with it.
func (*MapOf[K, V]) UnmarshalJSON ¶ added in v1.19.0
UnmarshalJSON reverse process of Marshal.
func (*MapOf[K, V]) Upsert ¶ added in v1.19.0
func (m *MapOf[K, V]) Upsert(key K, value V, cb UpsertCbOf[V]) (res V)
Upsert insert or update - updates existing element or inserts a new one using UpsertCbOf
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 RemoveCbOf ¶ added in v1.19.0
RemoveCbOf is a callback executed in a map.RemoveCbOf() call, while Lock is held If returns true, the element will be removed from the map
type SharedOf ¶ added in v1.19.0
type SharedOf[K comparable, V any] struct { // contains filtered or unexported fields }
SharedOf a "thread" safe string to anything map.
type Tuple ¶
type Tuple struct {
Key string
Val interface{}
}
Tuple used by the Iter & IterBuffered functions to wrap two variables together over a channel,
type TupleOf ¶ added in v1.19.0
type TupleOf[K comparable, V any] struct { Key K Val V }
TupleOf used by the Iter & IterBuffered functions to wrap two variables together over a channel,
type UpsertCb ¶
type UpsertCb func(exist bool, valueInMap interface{}, newValue interface{}) interface{}
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 UpsertCbOf ¶ added in v1.19.0
UpsertCbOf 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
Source Files
Directories