pmaps2

Documentation

Overview

Package pmaps2 contains resusable map types for other parl packages.

Index

• Constants
• type KeyRanger
  • func (r KeyRanger[K, V]) RangeFunc(key K, value V) (keepGoing bool)
• 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)) (rangedAll 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, hasValue 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)) (rangedAll 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
)

Types

type KeyRanger

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

KeyRanger is a tuple value-type

• used as local variable or function argument or return value causes no allocation
• taking its address causes allocation

func (KeyRanger[K, V]) RangeFunc

func (r KeyRanger[K, V]) RangeFunc(key K, value V) (keepGoing bool)

RangeFunc can be used with map Range methods

type Map

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

Map is a reusable promotable Go map

• 5 native Go Map functions: Get Put Delete Length Range
• convenience functions:
• — Clear using fast, scavenging re-create
• — Clone using range, optionally appending to provided instance
• — these methods require access to the underlying Go map
• not thread-safe:
• — zero-value delete can be implemented by consumer
• — range-Clear with zero-value write can be implemented by consumer
• — order methods List and Keys can be implemented by consumer

func NewMap

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

NewMap returns a reusable 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 and appended to
• delegates to maps.Clone 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)) (rangedAll bool)

Range traverses map bindings

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

type ThreadSafeMap

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

ThreadSafeMap is a thread-safe reusable promotable hash-map

• ThreadSafeMap is the innermost type providing thread-safety to consuming map implementations
• 5 native Go map functions: Get Put Delete Length Range
• — Delete optionally writes zero-value
• convenience methods:
• — Clone based on maps.Clone
• — Clear using fast recreate or maps.Range optionally writing zero-values
• lock control: Lock RLock
• order functions:
• — List unordered values
• ThreadSafeMap uses reader/writer mutual exclusion lock for thread-safety
• map mechnic is Go map

func NewThreadSafeMap

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

NewThreadSafeMap returns a thread-safe Go map

• stores self-refencing pointers

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, hasValue bool)

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

• hasValue 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)) (rangedAll bool)

Range traverses map bindings

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