README
¶
concurrent map 
正如 这里 和 这里所描述的, Go语言原生的map类型并不支持并发读写。concurrent-map提供了一种高性能的解决方案:通过对内部map进行分片，降低锁粒度，从而达到最少的锁等待时间(锁冲突)
在Go 1.9之前，go语言标准库中并没有实现并发map。在Go 1.9中，引入了sync.Map。新的sync.Map与此concurrent-map有几个关键区别。标准库中的sync.Map是专为append-only场景设计的。因此，如果您想将Map用于一个类似内存数据库，那么使用我们的版本可能会受益。你可以在golang repo上读到更多，这里 and 这里
译注:sync.Map在读多写少性能比较好，否则并发性能很差
用法
导入包:
import (
"github.com/Coloured-glaze/cmap"
)
go get "github.com/Coloured-glaze/cmap"
示例
// 创建一个新的 map.
m := cmap.New[int]()
// 设置变量m一个键为“key”值为“100”键值对
m.Set("key", 100)
// 从m中获取指定键值.
v, ok := m.Get("key")
// 删除键为“key”的项
m.Remove("key")
// 创建一个新的 map.
m := cmap.New[map[string]int]()
// 设置变量m一个键为 "user" 值为 map[string]int 键值对
m.Set("user", make(map[string]int))
// 从m中获取指定键值.
v, ok := m.Get("user")
// 删除键为“foo”的项
m.Remove("user")
更多使用示例请查看concurrent_map_test.go.
运行测试:
go test "github.com/Coloured-glaze/cmap"
贡献说明
我们非常欢迎大家的贡献。如欲合并贡献，请遵循以下指引:
- 新建一个issue,并且叙述为什么这么做(解决一个bug，增加一个功能，等等)
- 根据核心团队对上述问题的反馈，提交一个PR，描述变更并链接到该问题。
- 新代码必须具有测试覆盖率。
- 如果代码是关于性能问题的，则必须在流程中包括基准测试(无论是在问题中还是在PR中)。
- 一般来说，我们希望
concurrent-map尽可能简单，且与原生的map有相似的操作。当你新建issue时请注意这一点。
language
许可证
MIT (see LICENSE file)
Documentation
¶
Index ¶
- Variables
- type ConcurrentMap
- func (m ConcurrentMap[K, V]) Clear()
- func (m ConcurrentMap[K, V]) Count() int
- func (m ConcurrentMap[K, V]) Get(key K) (V, bool)
- func (m ConcurrentMap[K, V]) GetShard(key K) *ConcurrentMapShared[K, V]
- func (m ConcurrentMap[K, V]) Has(key K) bool
- func (m ConcurrentMap[K, V]) IsEmpty() bool
- func (m ConcurrentMap[K, V]) Items() map[K]V
- func (m ConcurrentMap[K, V]) Iter() <-chan Tuple[K, V]
- func (m ConcurrentMap[K, V]) IterBuffered() <-chan Tuple[K, V]
- func (m ConcurrentMap[K, V]) IterCb(fn IterCb[K, V])
- func (m ConcurrentMap[K, V]) Keys() []K
- func (m ConcurrentMap[K, V]) MSet(data map[K]V)
- func (m ConcurrentMap[K, V]) MarshalJSON() ([]byte, error)
- func (m ConcurrentMap[K, V]) Pop(key K) (v V, exists bool)
- func (m ConcurrentMap[K, V]) Remove(key K)
- func (m ConcurrentMap[K, V]) RemoveCb(key K, cb RemoveCb[K, V]) bool
- func (m ConcurrentMap[K, V]) Set(key K, value V)
- func (m ConcurrentMap[K, V]) SetIfAbsent(key K, value V) bool
- func (m *ConcurrentMap[K, V]) UnmarshalJSON(b []byte) (err error)
- func (m ConcurrentMap[K, V]) Upsert(key K, value V, cb UpsertCb[V]) (res V)
- type ConcurrentMapShared
- type IterCb
- type RemoveCb
- type Stringer
- type Tuple
- type UpsertCb
Constants ¶
This section is empty.
Variables ¶
var (
SHARD_COUNT = 32 // 默认map分片数量
)
Functions ¶
This section is empty.
Types ¶
type ConcurrentMap ¶
type ConcurrentMap[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.
一个 "线程" 安全的map 类型为 string:Anything 为了避免锁瓶颈，该map被划分为多个(SHARD_COUNT) 分片计数map。
func NewStringer ¶
func NewStringer[K Stringer, V any]() ConcurrentMap[K, V]
Creates a new concurrent map.
创建新的并发map
func NewWithCustomShardingFunction ¶
func NewWithCustomShardingFunction[K comparable, V any](sharding func(key K) uint32) ConcurrentMap[K, V]
Creates a new concurrent map.
创建新的并发map
func (ConcurrentMap[K, V]) Clear ¶
func (m ConcurrentMap[K, V]) Clear()
Clear removes all items from map.
Clear 将从map中删除所有项目。
func (ConcurrentMap[K, V]) Count ¶
func (m ConcurrentMap[K, V]) Count() int
Count returns the number of elements within the map.
Count返回map中元素的数量。
func (ConcurrentMap[K, V]) Get ¶
func (m ConcurrentMap[K, V]) Get(key K) (V, bool)
Get retrieves an element from map under given key.
Get 从给定key下的映射中检索元素。
func (ConcurrentMap[K, V]) GetShard ¶
func (m ConcurrentMap[K, V]) GetShard(key K) *ConcurrentMapShared[K, V]
GetShard returns shard under given key
GetShard 返回给定key下的map分片, 可进行锁操作
func (ConcurrentMap[K, V]) Has ¶
func (m ConcurrentMap[K, V]) Has(key K) bool
Looks up an item under specified key
查找指定key下的项目
func (ConcurrentMap[K, V]) IsEmpty ¶
func (m ConcurrentMap[K, V]) IsEmpty() bool
IsEmpty checks if map is empty.
IsEmpty检查map是否为空。
func (ConcurrentMap[K, V]) Items ¶
func (m ConcurrentMap[K, V]) Items() map[K]V
Items returns all items as map[string]V
Items 将所有项目返回为 map[string]V
func (ConcurrentMap[K, V]) Iter ¶
func (m ConcurrentMap[K, V]) Iter() <-chan Tuple[K, V]
Iter returns an iterator which could be used in a for range loop. Deprecated: using IterBuffered() will get a better performence
Iter 返回一个迭代器，可以在for range循环中使用。 不推荐：使用 IterBuffered() 将获得更好的性能
func (ConcurrentMap[K, V]) IterBuffered ¶
func (m ConcurrentMap[K, V]) IterBuffered() <-chan Tuple[K, V]
IterBuffered returns a buffered iterator which could be used in a for range loop.
IterBuffered 返回一个缓冲迭代器，可以在for range循环中使用。
func (ConcurrentMap[K, V]) IterCb ¶
func (m ConcurrentMap[K, V]) IterCb(fn IterCb[K, V])
Callback based iterator, cheapest way to read all elements in a map.
基于回调的迭代器，读取map中所有元素的最简易方法
func (ConcurrentMap[K, V]) Keys ¶
func (m ConcurrentMap[K, V]) Keys() []K
Keys returns all keys as []string
Keys 将所有key返回 []string
func (ConcurrentMap[K, V]) MSet ¶
func (m ConcurrentMap[K, V]) MSet(data map[K]V)
func (ConcurrentMap[K, V]) MarshalJSON ¶
func (m ConcurrentMap[K, V]) MarshalJSON() ([]byte, error)
Reviles ConcurrentMap "private" variables to json marshal.
将 ConcurrentMap 序列化为json.
func (ConcurrentMap[K, V]) Pop ¶
func (m ConcurrentMap[K, V]) Pop(key K) (v V, exists bool)
Pop removes an element from the map and returns it
Pop从map中删除元素并将其返回
func (ConcurrentMap[K, V]) Remove ¶
func (m ConcurrentMap[K, V]) Remove(key K)
Remove removes an element from the map.
Remove 从map中移除指定元素
func (ConcurrentMap[K, V]) RemoveCb ¶
func (m ConcurrentMap[K, V]) RemoveCb(key K, cb RemoveCb[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)
RemoveCb锁定包含key的分片，检索其当前值，并使用这些参数调用回调 如果回调返回true并且元素存在，它将从map中删除它 返回回调返回的值（即使元素不在map中）
func (ConcurrentMap[K, V]) Set ¶
func (m ConcurrentMap[K, V]) Set(key K, value V)
Sets the given value under the specified key.
设置指定key下的给定值。
func (ConcurrentMap[K, V]) SetIfAbsent ¶
func (m ConcurrentMap[K, V]) SetIfAbsent(key K, value V) bool
Sets the given value under the specified key if no value was associated with it.
如果没有值与指定键关联，则在指定键下设置给定值。
func (*ConcurrentMap[K, V]) UnmarshalJSON ¶
func (m *ConcurrentMap[K, V]) UnmarshalJSON(b []byte) (err error)
Reverse process of Marshal.
反序列化json
func (ConcurrentMap[K, V]) Upsert ¶
func (m ConcurrentMap[K, V]) Upsert(key K, value V, cb UpsertCb[V]) (res V)
Insert or Update - updates existing element or inserts a new one using UpsertCb
Insert 或 Update - 使用 UpsertCb 更新现有元素或插入新元素
type ConcurrentMapShared ¶
type ConcurrentMapShared[K comparable, V any] struct { // contains filtered or unexported fields }
A "thread" safe string to anything map.
一个key为string的线程安全的任意map
func (*ConcurrentMapShared[K, V]) GetMap ¶
func (cms *ConcurrentMapShared[K, V]) GetMap() map[K]V
Get map shard
获取map分片
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
为map中找到的每个键、值调用迭代器。 RLock用于给定碎片的所有调用，因此回调会获得分片的一致视图，但不会跨越分片
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
RemoveCb是在map中执行的回调。RemoveCb()调用，而Lock被保持 如果返回true，元素将从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,
由 Iter & IterBuffered 函数用于将两个变量包装在一个管道上，
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
回调以返回要插入到map中的新元素 它在锁定时被调用，因此不能 尝试访问同一map中的其他key，因为这可能会导致死锁，因为 Go sync.RWLock 不可重入
Source Files