Documentation
¶
Overview ¶
Package pmaps provides an unordered, thread-safe, RWMutex-mechanic map pmaps.RWMap.
Index ¶
- func GoMapSize[K comparable, V any](m map[K]V) (size uint64)
- func NewRWMap[K comparable, V any]() (rwMap parli.ThreadSafeMap[K, V])
- type RWMap
- func (m *RWMap) Clear(useRange ...bool)
- func (m *RWMap[K, V]) Clone() (clone parli.ThreadSafeMap[K, V])
- func (m *RWMap[K, V]) Clone2() (clone *RWMap[K, V])
- func (m *RWMap) Delete(key K, useZeroValue ...bool)
- func (m *RWMap) Get(key K) (value V, ok bool)
- func (m *RWMap) GetOrCreate(key K, newV func() (value *V), makeV func() (value V)) (value V, hasValue bool)
- func (m *RWMap[K, V]) Keys(n ...int) (keys []K)
- func (m *RWMap) Length() (length int)
- func (m *RWMap) List(n ...int) (list []V)
- func (m *RWMap) Put(key K, value V)
- func (m *RWMap[K, V]) PutIf(key K, value V, putIf func(value V) (doPut bool)) (wasNewKey bool)
- func (m *RWMap) Range(rangeFunc func(key K, value V) (keepGoing bool)) (rangedAll bool)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GoMapSize ¶ added in v0.4.75
func GoMapSize[K comparable, V any](m map[K]V) (size uint64)
GoMapSize returns the current size of the bucket array of Go map m
- size is 0 for a nil map
- size is 1 for an unallocated hash-table — rare case
- otherwise size is a power of 2
About Go map:
- Go map is a hash map
- a hash table is a space-time trade-off compared to array access
- size is how many slots m’s hash table currently has
- size may grow or shrink as m is modified
- a mapping of the hash value-space is used for hash-table array access
- each map slot contains a linked list of key-value pairs
- more slots is faster closing in on O(1) complexity, fewer slots saves memory
- Load factor is number of hash-table entries including collisions divided by hash table size
Source code:
- the map source code part of the runtime package is available online:
- — https://go.googlesource.com/go/+/refs/heads/master/src/runtime/map.go
- runtime source is typically installed on a computer that has Go:
- — module directory: …libexec/src, package directory: runtime
- — on macOS homebrew similar to: …/homebrew/Cellar/go/1.20.2/libexec/src
func NewRWMap ¶
func NewRWMap[K comparable, V any]() (rwMap parli.ThreadSafeMap[K, V])
NewRWMap returns a thread-safe map implementation
Types ¶
type RWMap ¶
type RWMap[K comparable, V any] struct { // contains filtered or unexported fields }
RWMap is a thread-safe mapping based on read/write mutex
- 5 native Go map functions: Get Put Delete Length Range
- — Delete optionally writes zero-value
- complex atomic methods:
- — GetOrCreate method is an atomic, thread-safe operation as opposed to Get-then-Put
- — PutIf is atomic, thread-safe operation
- convenience methods:
- — Clone Clone2 based on maps.Clone
- — Clear using fast recreate or maps.Range optionally writing zero-values
- order functions:
- — List unordered values
- — Keys unordered keys
- V is copied so if V is large or contains locks, use pointer to V type
- RWMap implements parli.ThreadSafeMap[K comparable, V any]
- —
- map mechanic is Go map
- RWMap uses reader/writer mutual exclusion lock for slightly higher performance
- Get methods are O(1)
- innermost type provides thread-safety
- outermost type provides map api
func NewRWMap2 ¶ added in v0.4.34
func NewRWMap2[K comparable, V any]() (rwMap *RWMap[K, V])
NewRWMap2 returns a thread-safe map implementation
func (*RWMap[K, V]) Clone ¶
func (m *RWMap[K, V]) Clone() (clone parli.ThreadSafeMap[K, V])
Clone returns a shallow clone of the map
func (*RWMap) GetOrCreate ¶
func (m *RWMap) GetOrCreate( key K, newV func() (value *V), makeV func() (value V), ) (value V, hasValue bool)
GetOrCreate returns an item from the map if it exists otherwise creates it.
- newV or makeV are invoked in the critical section, ie. these functions may not access the map or deadlock
- if a key is mapped, its value is returned
- otherwise, if newV and makeV are both nil, nil is returned.
- otherwise, if newV is present, it is invoked to return a pointer ot a value. A nil return value from newV causes panic. A new mapping is created using the value pointed to by the newV return value.
- otherwise, a mapping is created using whatever makeV returns
- newV and makeV may not access the map. The map’s write lock is held during their execution
- GetOrCreate is an atomic, thread-safe operation
- value insert is O(log n)
func (*RWMap[K, V]) Keys ¶ added in v0.4.47
Keys provides the mapping keys, undefined ordering
- O(n)
- invoked while holding RLock or Lock
func (*RWMap) List ¶
func (m *RWMap) List(n ...int) (list []V)
List provides the mapped values, undefined ordering
- O(n)
func (*RWMap[K, V]) PutIf ¶ added in v0.4.39
Putif is conditional Put depending on the return value from the putIf function
- if key does not exist in the map, the put is carried out and wasNewKey is true
- if key exists and putIf is nil or returns true, the put is carried out and wasNewKey is false
- if key exists and putIf returns false, the put is not carried out and wasNewKey is false
- during PutIf, the map cannot be accessed and the map’s write-lock is held
- PutIf is an atomic, thread-safe operation
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.