refcountmap

README

refcountmap - a reference counting generic map

Install:

go get github.com/memsql/refcountmap

---

The idea with refcountmap is that the value for each key is a singleton. When you ask for a value for a specific key, if that key isn't already in the map, then the value is created. If you ask for that same key again, you get another copy of that value. When you're done with a value, you release it. When all copies of the value have been released, the key is removed from the map.

The map is thread-safe.

An example

m := refcountmap.New[string](func() *Thing {
	return &Thing{}
})

thing1 := m.Get("hat")
thing2 := m.Get("hat")

// thing1 and thing2 should be pointers to the same Thing
	

Documentation

Index

• type Map
  • func New[K comparable, V any](newValue func() V) *Map[K, V]
  • func NewValueFromKey[K comparable, V any](newValue func(K) V) *Map[K, V]
  • func (m *Map[K, V]) Get(k K) (value V, release func(), loaded bool)
  • func (m *Map[K, V]) Load(k K) (value V, loaded bool)
  • func (m *Map[K, V]) Range(f func(K, V) bool)

Types

type Map

type Map[K comparable, V any] struct {
	gwrap.SyncMap[K, *counter[K, V]]
	// contains filtered or unexported fields
}

Map is a thread-safe map that with reference-counted values. Values are obtained with Get() and discarded when no longer needed. New values are created as needed.

func New

func New[K comparable, V any](newValue func() V) *Map[K, V]

New will use the newValue function to create new values when one does not already exist. Some return values from newValue() may be discarded without ever being returned.

Usually V should be a pointer. The type of V can be derived from the function, but the type of K cannot so the usuall invocation is like

m := refcountmap.New[keyType](func() valueType { return &valueType{} })

func NewValueFromKey

func NewValueFromKey[K comparable, V any](newValue func(K) V) *Map[K, V]

NewValueFromKey will use the newValue function to create new values when one does not already exist. Some return values from newValue() may be discarded without ever being returned.

func (*Map[K, V]) Get

func (m *Map[K, V]) Get(k K) (value V, release func(), loaded bool)

Get either returns an existing value for the given key (if there is an existing value) or it creates a new value and returns it.

The release() function that must be called when you are done with the returned value:

item, release, loaded := m.Get("key")
defer release()

func (*Map[K, V]) Load

func (m *Map[K, V]) Load(k K) (value V, loaded bool)

Load returns the current value for the key. It will not create a value if one does not exist. If loaded is false, the value is invalid. Load does not increase the reference count on the value returned.

func (*Map[K, V]) Range

func (m *Map[K, V]) Range(f func(K, V) bool)

Range is like sync.Map.Range(). It iterates over the keys in the map. There is no guarantee that a key won't be removed during iteration. The reference count for the returned key is not incremented by Range.