containers

Documentation

Overview

Package containers provides generic containers.

Example (BenchConcurrentMap)

package main

import (
	"fmt"
	"testing"

	"github.com/siderolabs/gen/containers"
	"github.com/siderolabs/gen/xsync"
)

func main() {
	var sink int

	benchResult := testing.Benchmark(func(b *testing.B) {
		b.ReportAllocs()

		var m containers.ConcurrentMap[int, *xsync.Once[int]]

		for i := 0; i < b.N; i++ {
			variable := 0

			res, _ := m.GetOrCall(10, func() *xsync.Once[int] {
				return &xsync.Once[int]{}
			})

			sink = res.Do(func() int {
				variable++

				return variable
			})
		}
	})

	if benchResult.AllocsPerOp() > 0 {
		fmt.Println("this benchmark should not allocate memory")
	}

	fmt.Println("ok")

	_ = sink
}

Output:

ok

Index

• type BiMap
  • func (m *BiMap[K, V]) Clear()
  • func (m *BiMap[K, V]) ForEach(f func(K, V))
  • func (m *BiMap[K, V]) Get(key K) (V, bool)
  • func (m *BiMap[K, V]) GetInverse(val V) (K, bool)
  • func (m *BiMap[K, V]) Remove(key K)
  • func (m *BiMap[K, V]) RemoveInverse(val V)
  • func (m *BiMap[K, V]) Set(key K, val V)
• type ConcurrentMap
  • func (m *ConcurrentMap[K, V]) Clear()
  • func (m *ConcurrentMap[K, V]) ForEach(f func(K, V))
  • func (m *ConcurrentMap[K, V]) Get(key K) (V, bool)
  • func (m *ConcurrentMap[K, V]) GetOrCall(key K, fn func() V) (V, bool)
  • func (m *ConcurrentMap[K, V]) GetOrCreate(key K, val V) (V, bool)
  • func (m *ConcurrentMap[K, V]) Len() int
  • func (m *ConcurrentMap[K, V]) Remove(key K)
  • func (m *ConcurrentMap[K, V]) RemoveAndGet(key K) (V, bool)
  • func (m *ConcurrentMap[K, V]) Reset()
  • func (m *ConcurrentMap[K, V]) Set(key K, val V)
• type LazyBiMap
  • func (m *LazyBiMap[K, V]) Clear()
  • func (m *LazyBiMap[K, V]) ForEach(f func(K, V))
  • func (m *LazyBiMap[K, V]) Get(key K) (V, bool)
  • func (m *LazyBiMap[K, V]) GetInverse(value V) (K, bool)
  • func (m *LazyBiMap[K, V]) GetOrCreate(key K) (V, error)
  • func (m *LazyBiMap[K, V]) Remove(key K)
  • func (m *LazyBiMap[K, V]) RemoveInverse(value V)
• type LazyMap
  • func (m *LazyMap[K, V]) Clear()
  • func (m *LazyMap[K, V]) ForEach(f func(K, V))
  • func (m *LazyMap[K, V]) Get(key K) (V, bool)
  • func (m *LazyMap[K, V]) GetOrCreate(key K) (V, error)
  • func (m *LazyMap[K, V]) Remove(key K)

Examples

• Package (BenchConcurrentMap)

Types

type BiMap

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

BiMap (or “bidirectional map”) is a special kind of map that maintains an inverse view of the map while ensuring that no duplicate values are present and a value can always be used safely to get the key back.

func (*BiMap[K, V]) Clear

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

Clear removes all key-value pairs.

func (*BiMap[K, V]) ForEach

func (m *BiMap[K, V]) ForEach(f func(K, V))

ForEach calls the given function for each key-value pair.

func (*BiMap[K, V]) Get

func (m *BiMap[K, V]) Get(key K) (V, bool)

Get returns the value for the given key.

func (*BiMap[K, V]) GetInverse

func (m *BiMap[K, V]) GetInverse(val V) (K, bool)

GetInverse returns the key for the given value.

func (*BiMap[K, V]) Remove

func (m *BiMap[K, V]) Remove(key K)

Remove deletes the value for the given key.

func (*BiMap[K, V]) RemoveInverse

func (m *BiMap[K, V]) RemoveInverse(val V)

RemoveInverse deletes the key for the given value.

func (*BiMap[K, V]) Set

func (m *BiMap[K, V]) Set(key K, val V)

Set sets the value for the given key.

type ConcurrentMap

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

ConcurrentMap is a map that can be safely accessed from multiple goroutines.

func (*ConcurrentMap[K, V]) Clear

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

Clear removes all key-value pairs.

func (*ConcurrentMap[K, V]) ForEach

func (m *ConcurrentMap[K, V]) ForEach(f func(K, V))

ForEach calls the given function for each key-value pair.

func (*ConcurrentMap[K, V]) Get

func (m *ConcurrentMap[K, V]) Get(key K) (V, bool)

Get returns the value for the given key.

func (*ConcurrentMap[K, V]) GetOrCall

func (m *ConcurrentMap[K, V]) GetOrCall(key K, fn func() V) (V, bool)

GetOrCall returns the existing value for the key if present. Otherwise, it calls fn, stores the result and returns it. The loaded result is true if the value was loaded, false if it was created using fn.

The main reason for this function is to avoid unnecessary allocations if you use pointer types as values, since compiler cannot prove that the value does not escape if it's not stored.

func (*ConcurrentMap[K, V]) GetOrCreate

func (m *ConcurrentMap[K, V]) GetOrCreate(key K, val V) (V, bool)

GetOrCreate 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 (*ConcurrentMap[K, V]) Len

func (m *ConcurrentMap[K, V]) Len() int

Len returns the number of elements in the map.

func (*ConcurrentMap[K, V]) Remove

func (m *ConcurrentMap[K, V]) Remove(key K)

Remove removes the value for the given key.

func (*ConcurrentMap[K, V]) RemoveAndGet

func (m *ConcurrentMap[K, V]) RemoveAndGet(key K) (V, bool)

RemoveAndGet removes the value for the given key and returns it if it exists.

func (*ConcurrentMap[K, V]) Reset

func (m *ConcurrentMap[K, V]) Reset()

Reset resets the underlying map.

func (*ConcurrentMap[K, V]) Set

func (m *ConcurrentMap[K, V]) Set(key K, val V)

Set sets the value for the given key.

type LazyBiMap

type LazyBiMap[K comparable, V comparable] struct {
	Creator func(K) (V, error)
	// contains filtered or unexported fields
}

LazyBiMap is like BiMap but creates values on demand.

func (*LazyBiMap[K, V]) Clear

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

Clear removes all values.

func (*LazyBiMap[K, V]) ForEach

func (m *LazyBiMap[K, V]) ForEach(f func(K, V))

ForEach calls the given function for each key-value pair.

func (*LazyBiMap[K, V]) Get

func (m *LazyBiMap[K, V]) Get(key K) (V, bool)

Get returns the value for the given key.

func (*LazyBiMap[K, V]) GetInverse

func (m *LazyBiMap[K, V]) GetInverse(value V) (K, bool)

GetInverse returns the key for the given value.

func (*LazyBiMap[K, V]) GetOrCreate

func (m *LazyBiMap[K, V]) GetOrCreate(key K) (V, error)

GetOrCreate returns the value for the given key.

func (*LazyBiMap[K, V]) Remove

func (m *LazyBiMap[K, V]) Remove(key K)

Remove removes the value for the given key.

func (*LazyBiMap[K, V]) RemoveInverse

func (m *LazyBiMap[K, V]) RemoveInverse(value V)

RemoveInverse removes the key for the given value.

type LazyMap

type LazyMap[K comparable, V comparable] struct {
	Creator func(K) (V, error)
	// contains filtered or unexported fields
}

LazyMap is like usual map but creates values on demand.

func (*LazyMap[K, V]) Clear

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

Clear removes all key-value pairs.

func (*LazyMap[K, V]) ForEach

func (m *LazyMap[K, V]) ForEach(f func(K, V))

ForEach calls the given function for each key-value pair.

func (*LazyMap[K, V]) Get

func (m *LazyMap[K, V]) Get(key K) (V, bool)

Get returns the value for the given key.

func (*LazyMap[K, V]) GetOrCreate

func (m *LazyMap[K, V]) GetOrCreate(key K) (V, error)

GetOrCreate returns the value for the given key. It creates it using Creator if it doesn't exist.

func (*LazyMap[K, V]) Remove

func (m *LazyMap[K, V]) Remove(key K)

Remove deletes the value for the given key.