README
¶
syncmap
syncmap.Map is sync.Map using generics.
syncmap.Map has methods that are same as sync.Map. e.g. Store, Load, LoadOrStore, LoadAndDelete, Delete, Range
Usage
Import
import "github.com/shiolier/syncmap"
Init
// empty map
smap := &syncmap.Map[string, int]{}
// empty map
smap := syncmap.NewMap[string, int](nil)
// OR map[K]V => *syncmap.Map[K, V]
m := map[string]int{"foo": 100, "bar": 200}
smap := syncmap.NewMap(m)
Store (thread safe)
smap.Store("baz", 300)
Load (thread safe)
foo, ok := smap.Load("foo")
if !ok {
fmt.Println("foo did not exist")
}
LoadOrStore (thread safe)
qux, loaded := smap.LoadOrStore("qux", 400)
if loaded {
fmt.Println("qux exists")
} else {
fmt.Println("store the value because qux did not exist")
}
LoadAndDelete (thread safe)
qux, loaded := smap.LoadAndDelete("qux")
if loaded {
fmt.Println("qux exists")
} else {
fmt.Println("qux did not exist")
}
Delete (thread safe)
smap.Delete("baz")
Range (thread safe)
smap.Range(func(key string, value int) bool {
fmt.Printf("%s: %d\n", key, value)
return true
})
Supports json.Marshal and json.Unmarshal
// json.Marshal
js, err := json.Marshal(smap)
if err != nil {
panic(err)
}
// Print json string
fmt.Println(string(js))
// empty map
smap = syncmap.NewMap[string, int](nil)
// json.Unmarshal
if err := json.Unmarshal(js, smap); err != nil {
panic(err)
}
When using your own type
// Key
type MyKey struct {
Num int
Str string
}
// MarshalJSKey returns the json key string
func (k MyKey) MarshalJSKey() (string, error) {
return fmt.Sprintf("%d:%s", k.Num, k.Str), nil
}
// UnmarshalJSKey parses the json key string
func (k *MyKey) UnmarshalJSKey(keystr string) error {
ss := strings.Split(keystr, ":")
num, err := strconv.Atoi(ss[0])
if err != nil {
return err
}
k.Num = num
k.Str = strings.Join(ss[1:], ":")
return nil
}
// Value
type MyValue struct {
// can use json tag
Foo int `json:"foo"`
Bar string
}
// Init
smap := syncmap.NewMap[MyKey, MyValue](nil)
// Store
smap.Store(MyKey{
Num: 111,
Str: "ABC",
}, MyValue{
Foo: 222,
Bar: "DEF",
})
smap.Store(MyKey{
Num: 333,
Str: "GHI:JKL",
}, MyValue{
Foo: 444,
Bar: "MNO",
})
// Marshal
js, err := json.Marshal(smap)
if err != nil {
fmt.Fprintln(os.Stderr, err)
return
}
// Print json string
fmt.Println(string(js))
// {"111:ABC":{"foo":222,"Bar":"DEF"},"333:GHI:JKL":{"foo":444,"Bar":"MNO"}}
// empty map
smap = syncmap.Map[MyKey, MyValue]{}
// Unmarshal
if err := json.Unmarshal(js, smap); err != nil {
fmt.Fprintln(os.Stderr, err)
return
}
// Range
smap.Range(func(key MyKey, value MyValue) bool {
fmt.Printf("%v: %v\n", key, value)
return true
})
/*
{111 ABC}: {222 DEF}
{333 GHI:JKL}: {444 MNO}
*/
Benchmark
Compare with WrapperMap[K, V] that is sync.Map wrapped with generics
Use [int, int] for type parameters [K, V]
goos: darwin
goarch: amd64
pkg: github.com/shiolier/syncmap
cpu: Intel(R) Core(TM) i5-3210M CPU @ 2.50GHz
BenchmarkLoadMostlyHits/*WrapperMap 51769129 23.38 ns/op 0 B/op 0 allocs/op
BenchmarkLoadMostlyHits/*Map 49294209 23.71 ns/op 0 B/op 0 allocs/op
BenchmarkLoadMostlyMisses/*WrapperMap 86073642 13.97 ns/op 0 B/op 0 allocs/op
BenchmarkLoadMostlyMisses/*Map 54911031 22.43 ns/op 0 B/op 0 allocs/op
BenchmarkLoadOrStoreBalanced/*WrapperMap 1775521 673.9 ns/op 93 B/op 2 allocs/op
BenchmarkLoadOrStoreBalanced/*Map 3079636 326.9 ns/op 36 B/op 1 allocs/op
BenchmarkLoadOrStoreUnique/*WrapperMap 1000000 1168 ns/op 163 B/op 4 allocs/op
BenchmarkLoadOrStoreUnique/*Map 1765795 645.7 ns/op 113 B/op 2 allocs/op
BenchmarkLoadOrStoreCollision/*WrapperMap 55630494 20.86 ns/op 0 B/op 0 allocs/op
BenchmarkLoadOrStoreCollision/*Map 48463934 24.44 ns/op 0 B/op 0 allocs/op
BenchmarkLoadAndDeleteBalanced/*WrapperMap 56891140 20.51 ns/op 0 B/op 0 allocs/op
BenchmarkLoadAndDeleteBalanced/*Map 48169279 25.21 ns/op 0 B/op 0 allocs/op
BenchmarkLoadAndDeleteUnique/*WrapperMap 124337067 9.726 ns/op 0 B/op 0 allocs/op
BenchmarkLoadAndDeleteUnique/*Map 60827192 19.44 ns/op 0 B/op 0 allocs/op
BenchmarkLoadAndDeleteCollision/*WrapperMap 121662361 9.720 ns/op 0 B/op 0 allocs/op
BenchmarkLoadAndDeleteCollision/*Map 59067524 19.58 ns/op 0 B/op 0 allocs/op
BenchmarkRange/*WrapperMap 114358 10445 ns/op 0 B/op 0 allocs/op
BenchmarkRange/*Map 50613 23094 ns/op 0 B/op 0 allocs/op
BenchmarkAdversarialAlloc/*WrapperMap 3588988 345.7 ns/op 39 B/op 0 allocs/op
BenchmarkAdversarialAlloc/*Map 4619600 268.7 ns/op 26 B/op 0 allocs/op
BenchmarkAdversarialDelete/*WrapperMap 9616904 138.1 ns/op 17 B/op 0 allocs/op
BenchmarkAdversarialDelete/*Map 12149572 101.3 ns/op 10 B/op 0 allocs/op
BenchmarkDeleteCollision/*WrapperMap 100000000 11.41 ns/op 0 B/op 0 allocs/op
BenchmarkDeleteCollision/*Map 57604394 21.07 ns/op 0 B/op 0 allocs/op
Documentation
¶
Index ¶
- type JSKeyMarshaler
- type JSKeyUnmarshaler
- type Map
- func (m *Map[K, V]) Delete(key K)
- func (m *Map[K, V]) Load(key K) (value V, ok bool)
- func (m *Map[K, V]) LoadAndDelete(key K) (value V, loaded bool)
- func (m *Map[K, V]) LoadOrStore(key K, value V) (actual V, loaded bool)
- func (m *Map[K, V]) Map() map[K]V
- func (m *Map[K, V]) MarshalJSON() ([]byte, error)
- func (m *Map[K, V]) Range(f func(key K, value V) bool)
- func (m *Map[K, V]) Store(key K, value V)
- func (m *Map[K, V]) UnmarshalJSON(bs []byte) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type JSKeyMarshaler ¶
type JSKeyMarshaler interface {
// MarshalJSKey returns the json key string
MarshalJSKey() (string, error)
}
JSKeyMarshaler is interface for type parameter K
type JSKeyUnmarshaler ¶
type JSKeyUnmarshaler interface {
// UnmarshalJSKey parses the json key string
UnmarshalJSKey(keystr string) error
}
JSKeyUnmarshaler is interface for type parameter K
type Map ¶
type Map[K comparable, V any] struct { // contains filtered or unexported fields }
Map is like a Go map[interface{}]interface{} but is safe for concurrent use by multiple goroutines without additional locking or coordination. Loads, stores, and deletes run in amortized constant time.
The Map type is specialized. Most code should use a plain Go map instead, with separate locking or coordination, for better type safety and to make it easier to maintain other invariants along with the map content.
The Map type is optimized for two common use cases: (1) when the entry for a given key is only ever written once but read many times, as in caches that only grow, or (2) when multiple goroutines read, write, and overwrite entries for disjoint sets of keys. In these two cases, use of a Map may significantly reduce lock contention compared to a Go map paired with a separate Mutex or RWMutex.
The zero Map is empty and ready for use. A Map must not be copied after first use.
func NewMap ¶
func NewMap[K comparable, V any](m map[K]V) (smap *Map[K, V])
func (*Map[K, V]) 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[K, V]) 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[K, V]) 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[K, V]) MarshalJSON ¶
MarshalJSON implements json.Marshaler
func (*Map[K, V]) 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 (including by f), Range may reflect any mapping for that key from any point during the Range call. Range does not block other methods on the receiver; even f itself may call any method on m.
Range may be O(N) with the number of elements in the map even if f returns false after a constant number of calls.
func (*Map[K, V]) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler
Source Files