cmap

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"
)

go get "github.com/orcaman/concurrent-map"

The package is now imported under the "cmap" namespace.

example

	// Create a new map.
	m := cmap.New()
	// Sets item within map, sets "bar" under key "foo"
	m.Set("foo", "bar")

	// Retrieve item from map.
	if val, ok := m.Get("foo"); ok {
		bar := val.(string)
	}
	// 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"

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-map as simple as possible and as similar to the native map. Please keep this in mind when opening issues.

language

• 中文说明

license

MIT (see LICENSE file)

Documentation

Index

• type IterCb
• type Map
  • func New(options ...OptionFn) *Map
  • func (m Map) Clear()
  • func (m Map) Count() int
  • func (m Map) Del(key string)
  • func (m Map) Get(key string) (interface{}, bool)
  • func (m Map) GetShard(key string) *Shared
  • func (m Map) GetString(key string) (string, bool)
  • func (m Map) Has(key string) bool
  • func (m Map) IsEmpty() bool
  • func (m Map) Items() map[string]interface{}
  • func (m Map) Iter() <-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) 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 Option
• type OptionFn
  • func WithShardCount(v int) OptionFn
• type RemoveCb
• type Shared
• type Tuple
• type UpsertCb

Types

type IterCb

type IterCb func(key string, v interface{})

IterCb is 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 Map

type Map struct {
	Shared     []*Shared
	ShardCount int
}

Map is a "thread" safe map of type string:Anything. To avoid lock bottlenecks this map is dived to several (ShardCount) map shards.

func New

func New(options ...OptionFn) *Map

New creates a new concurrent map.

func (Map) Clear

func (m Map) Clear()

Clear removes all items from map.

func (Map) Count

func (m Map) Count() int

Count returns the number of elements within the map.

func (Map) Del

func (m Map) Del(key string)

Del removes an element from the map.

func (Map) Get

func (m Map) Get(key string) (interface{}, bool)

Get retrieves an element from map under given key.

func (Map) GetShard

func (m Map) GetShard(key string) *Shared

GetShard returns shard under given key

func (Map) GetString

func (m Map) GetString(key string) (string, bool)

GetString retrieves a string element from map under given key.

func (Map) Has

func (m Map) Has(key string) bool

Has looks up an item under specified key.

func (Map) IsEmpty

func (m Map) IsEmpty() bool

IsEmpty checks if map is empty.

func (Map) Items

func (m Map) Items() map[string]interface{}

Items returns all items as map[string]interface{}

func (Map) Iter

func (m Map) Iter() <-chan Tuple

Iter returns a buffered iterator which could be used in a for range loop.

func (Map) IterCb

func (m Map) IterCb(fn IterCb)

IterCb is callback based iterator, cheapest way to read all elements in a map.

func (Map) Keys

func (m Map) Keys() []string

Keys returns all keys as []string

func (Map) MSet

func (m Map) MSet(data map[string]interface{})

func (Map) MarshalJSON

func (m Map) MarshalJSON() ([]byte, error)

MarshalJSON reviles Map "private" variables to json marshal.

func (Map) Pop

func (m Map) Pop(key string) (v interface{}, exists bool)

Pop removes an element from the map and returns it

func (Map) RemoveCb

func (m Map) RemoveCb(key string, cb RemoveCb) 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 (Map) Set

func (m Map) Set(key string, value interface{})

Set sets the given value under the specified key.

func (Map) SetIfAbsent

func (m Map) SetIfAbsent(key string, value interface{}) bool

SetIfAbsent sets the given value under the specified key if no value was associated with it.

func (Map) Upsert

func (m Map) Upsert(key string, value interface{}, cb UpsertCb) (res interface{})

Upsert is Insert or Update - updates existing element or inserts a new one using UpsertCb

type Option

type Option struct {
	ShardCount int
}

type OptionFn

type OptionFn func(o *Option)

func WithShardCount

func WithShardCount(v int) OptionFn

type RemoveCb

type RemoveCb func(key string, v interface{}, exists bool) bool

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 Shared

type Shared struct {
	sync.RWMutex // Read Write mutex, guards access to internal map.
	// contains filtered or unexported fields
}

Shared is a "thread" safe string to anything map.

type Tuple

type Tuple struct {
	Key string
	Val interface{}
}

Tuple is 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 is 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