pmaps

Documentation

Overview

RWMap is a one-liner thread-safe mapping. RWMap implements parli.ThreadSafeMap[K comparable, V any].

Index

• Constants
• func GoMapSize[K comparable, V any](m map[K]V) (size uint64)
• func NewRWMap[K comparable, V any]() (rwMap parli.ThreadSafeMap[K, V])
• type Map
  • func NewMap[K comparable, V any]() (mapping *Map[K, V])
  • func (m *Map[K, V]) Clear()
  • func (m *Map[K, V]) Clone(mp ...*Map[K, V]) (clone *Map[K, V])
  • func (m *Map[K, V]) Delete(key K)
  • func (m *Map[K, V]) Get(key K) (value V, ok bool)
  • func (m *Map[K, V]) Length() (length int)
  • func (m *Map[K, V]) Put(key K, value V)
  • func (m *Map[K, V]) Range(rangeFunc func(key K, value V) (keepGoing bool))
• type RWMap
  • func NewRWMap2[K comparable, V any]() (rwMap *RWMap[K, V])
  • 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, ok bool)
  • func (m *RWMap[K, V]) Keys(n ...int) (list []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))
• type ThreadSafeMap
  • func NewThreadSafeMap[K comparable, V any]() (m *ThreadSafeMap[K, V])
  • func (m *ThreadSafeMap[K, V]) Clear(useRange ...bool)
  • func (m *ThreadSafeMap[K, V]) Clone() (clone *ThreadSafeMap[K, V])
  • func (m *ThreadSafeMap[K, V]) Delete(key K, useZeroValue ...bool)
  • func (m *ThreadSafeMap[K, V]) Get(key K) (value V, ok bool)
  • func (m *ThreadSafeMap[K, V]) Length() (length int)
  • func (m *ThreadSafeMap[K, V]) List(n int) (list []V)
  • func (m *ThreadSafeMap[K, V]) Lock() (unlock func())
  • func (m *ThreadSafeMap[K, V]) Put(key K, value V)
  • func (m *ThreadSafeMap[K, V]) RLock() (runlock func())
  • func (m *ThreadSafeMap[K, V]) Range(rangeFunc func(key K, value V) (keepGoing bool))

Constants

const (
	// with [ThreadSafeMap.Delete] sets the mapping value to the
	// zero-value prior to delete
	SetZeroValue = true
	// with [ThreadSafeMap.Clear], the map is cleared using range
	// and delete of all keys rather than re-created
	RangeDelete = true
)

Functions

func GoMapSize

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 Map

type Map[K comparable, V any] struct {
	// contains filtered or unexported fields
}

Map is a Go Map as a reusable promotable field

• native Go Map functions: Get Put Delete Length Range
• convenience functions: Clear Clone
• — those methods are implemented because they require access to the underlying Go map

func NewMap

func NewMap[K comparable, V any]() (mapping *Map[K, V])

NewMap returns a resusable Go Map object

func (*Map[K, V]) Clear

func (m *Map[K, V]) Clear()

Clear empties the map

• clears by re-initializing the map
• when instead ranging and deleting all keys, the unused size of the map is retained

func (*Map[K, V]) Clone

func (m *Map[K, V]) Clone(mp ...*Map[K, V]) (clone *Map[K, V])

Clone returns a shallow clone of the map

• mp is an optional pointer to an already allocated map instance to be used
• clone is done by ranging all keys

func (*Map[K, V]) Delete

func (m *Map[K, V]) Delete(key K)

Delete removes mapping for key

• if key is not mapped, the map is unchanged.
• O(log n)

func (*Map[K, V]) Get

func (m *Map[K, V]) Get(key K) (value V, ok bool)

Get returns the value mapped by key or the V zero-value otherwise

• ok: true if a mapping was found
• O(1)

func (*Map[K, V]) Length

func (m *Map[K, V]) Length() (length int)

Length returns the number of mappings

func (*Map[K, V]) Put

func (m *Map[K, V]) Put(key K, value V)

Put create or replaces a mapping

func (*Map[K, V]) Range

func (m *Map[K, V]) Range(rangeFunc func(key K, value V) (keepGoing bool))

Range traverses map bindings

• iterates over map until rangeFunc returns false
• order is undefined
• similar to: func (*sync.Map).Range(f func(key any, value any) bool)

type RWMap

type RWMap[K comparable, V any] struct {
	// contains filtered or unexported fields
}

RWMap is a one-liner thread-safe mapping. RWMap implements parli.ThreadSafeMap[K comparable, V any].

• GetOrCreate method is an atomic, thread-safe operation as opposed to Get-then-Put
• PutIf is atomic, thread-safe operation
• native Go map functions: Get Put Delete Length Range
• convenience methods: Clone Clone2 Clear
• order functions: List Keys
• V is copied so if size of V is large or V contains locks, use pointer
• RWMap uses reader/writer mutual exclusion lock for slightly higher performance.
• Get methods are O(1)

func NewRWMap2

func NewRWMap2[K comparable, V any]() (rwMap *RWMap[K, V])

NewRWMap2 returns a thread-safe map implementation

func (*RWMap) Clear

func (m *RWMap) Clear(useRange ...bool)

Clear empties the map

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[K, V]) Clone2

func (m *RWMap[K, V]) Clone2() (clone *RWMap[K, V])

Clone returns a shallow clone of the map

func (*RWMap) Delete

func (m *RWMap) Delete(key K, useZeroValue ...bool)

func (*RWMap) Get

func (m *RWMap) Get(key K) (value V, ok bool)

func (*RWMap) GetOrCreate

func (m *RWMap) GetOrCreate(
	key K,
	newV func() (value *V),
	makeV func() (value V),
) (value V, ok 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

func (m *RWMap[K, V]) Keys(n ...int) (list []K)

Keys provides the mapping keys, undefined ordering

• O(n)
• invoked while holding RLock or Lock

func (*RWMap) Length

func (m *RWMap) Length() (length int)

func (*RWMap) List

func (m *RWMap) List(n ...int) (list []V)

List provides the mapped values, undefined ordering

• O(n)

func (*RWMap) Put

func (m *RWMap) Put(key K, value V)

func (*RWMap[K, V]) PutIf

func (m *RWMap[K, V]) PutIf(key K, value V, putIf func(value V) (doPut bool)) (wasNewKey bool)

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

func (*RWMap) Range

func (m *RWMap) Range(rangeFunc func(key K, value V) (keepGoing bool))

type ThreadSafeMap

type ThreadSafeMap[K comparable, V any] struct {
	// contains filtered or unexported fields
}

ThreadSafeMap is a thread-safe reusable promotable Go map

• native Go map functions: Get Put Delete Length Range
• convenience functions: Clear Clone
• — those methods need access to the Go map
• lock control: Lock RLock
• ThreadSafeMap uses reader/writer mutual exclusion lock for thread-safety

func NewThreadSafeMap

func NewThreadSafeMap[K comparable, V any]() (m *ThreadSafeMap[K, V])

NewThreadSafeMap returns a thread-safe Go map

func (*ThreadSafeMap[K, V]) Clear

func (m *ThreadSafeMap[K, V]) Clear(useRange ...bool)

Clear empties the map

• if useRange is RangeDelete, the map is cleared by iterating and deleteing all keys
• invoked while holding Lock

func (*ThreadSafeMap[K, V]) Clone

func (m *ThreadSafeMap[K, V]) Clone() (clone *ThreadSafeMap[K, V])

Clone returns a shallow clone of the map

• clone is done by ranging all keys
• invoked while holding RLock or Lock

func (*ThreadSafeMap[K, V]) Delete

func (m *ThreadSafeMap[K, V]) Delete(key K, useZeroValue ...bool)

Delete removes mapping for key

• if key is not mapped, the map is unchanged
• if useZeroValue is pmaps.SetZeroValue, the mapping value is first set to the zero-value. This prevents temporary memory leaks when V contains pointers to large objects
• O(log n)
• invoked while holding Lock

func (*ThreadSafeMap[K, V]) Get

func (m *ThreadSafeMap[K, V]) Get(key K) (value V, ok bool)

Get returns the value mapped by key or the V zero-value otherwise.

• the ok return value is true if a mapping was found.
• invoked while holding Lock or RLock
• O(1)

func (*ThreadSafeMap[K, V]) Length

func (m *ThreadSafeMap[K, V]) Length() (length int)

Length returns the number of mappings

• invoked while holding RLock or Lock

func (*ThreadSafeMap[K, V]) List

func (m *ThreadSafeMap[K, V]) List(n int) (list []V)

List provides the mapped values, undefined ordering

• O(n)
• invoked while holding RLock or Lock

func (*ThreadSafeMap[K, V]) Lock

func (m *ThreadSafeMap[K, V]) Lock() (unlock func())

allows consumers to obtain the write lock

• returns a function releasing the lock

func (*ThreadSafeMap[K, V]) Put

func (m *ThreadSafeMap[K, V]) Put(key K, value V)

Put creates or replaces a mapping

• invoked while holding Lock

func (*ThreadSafeMap[K, V]) RLock

func (m *ThreadSafeMap[K, V]) RLock() (runlock func())

allows consumers to obtain the read lock

• returns a function releasing the lock

func (*ThreadSafeMap[K, V]) Range

func (m *ThreadSafeMap[K, V]) Range(rangeFunc func(key K, value V) (keepGoing bool))

Range traverses map bindings

• iterates over map until rangeFunc returns false
• similar to: func (*sync.Map).Range(f func(key any, value any) bool)
• invoked while holding RLock or Lock