containers

Documentation

Overview

Package containers provides generic containers.

Example (BenchConcurrentMap)

package main

import (
	"fmt"
	"sync"
	"testing"

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

func main() {
	var sink int

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

		var m containers.ConcurrentMap[int, func() int]

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

			res, _ := m.GetOrCall(10, func() func() int {
				return sync.OnceValue(func() int {
					variable++

					return variable
				})
			})

			sink = res()
		}
	})

	if allocsPerOp := benchResult.AllocsPerOp(); allocsPerOp > 1 {
		fmt.Printf("this benchmark should not make more than one allocation, but it makes %d allocations per operation", allocsPerOp)
	}

	fmt.Println("ok")
	fmt.Println(sink)

}

Output:

ok
1

Index

• type BiMap
  • func (m *BiMap[K, V]) Clear()
  • func (m *BiMap[K, V]) FilterInPlace(f func(K, V) bool)
  • 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]) Len() int
  • 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]) FilterInPlace(f func(K, V) bool)
  • 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]) FilterInPlace(f func(K, V) bool)
  • 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]) Len() int
  • 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]) FilterInPlace(f func(K, V) bool)
  • 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]) Len() int
  • func (m *LazyMap[K, V]) Remove(key K)
• type SyncMap
  • func (m *SyncMap[K, V]) CompareAndDelete(key K, old V) (deleted bool)
  • func (m *SyncMap[K, V]) CompareAndSwap(key K, old, newValue V) bool
  • func (m *SyncMap[K, V]) Delete(key K)
  • func (m *SyncMap[K, V]) Load(key K) (value V, ok bool)
  • func (m *SyncMap[K, V]) LoadAndDelete(key K) (value V, loaded bool)
  • func (m *SyncMap[K, V]) LoadOrStore(key K, value V) (actual V, loaded bool)
  • func (m *SyncMap[K, V]) Range(f func(key K, value V) bool)
  • func (m *SyncMap[K, V]) Store(key K, value V)
  • func (m *SyncMap[K, V]) Swap(key K, value V) (previous V, loaded bool)

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]) FilterInPlace

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

FilterInPlace calls the given function for each key-value pair and returns a new map with the filtered values.

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]) Len

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

Len returns the number of key-value pairs.

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]) FilterInPlace

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

FilterInPlace calls the given function for each key-value pair and removes the key-value pair if the function returns false.

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]) FilterInPlace

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

FilterInPlace calls the given function for each key-value pair and returns a new map with the filtered 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]) Len

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

Len returns the number of key-value pairs.

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]) FilterInPlace

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

FilterInPlace calls the given function for each key-value pair and returns a new map with the filtered values.

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]) Len

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

Len returns the number of key-value pairs.

func (*LazyMap[K, V]) Remove

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

Remove deletes the value for the given key.

type SyncMap

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

SyncMap is a wrapper around sync.Map that provides type safety.

func (*SyncMap[K, V]) CompareAndDelete

func (m *SyncMap[K, V]) CompareAndDelete(key K, old V) (deleted bool)

CompareAndDelete deletes the entry for key if its value is equal to old. The old value must be of a comparable type.

If there is no current value for key in the map, CompareAndDelete returns false.

func (*SyncMap[K, V]) CompareAndSwap

func (m *SyncMap[K, V]) CompareAndSwap(key K, old, newValue V) bool

CompareAndSwap swaps the old and new values for key if the value stored in the map is equal to old. The old value must be of a comparable type.

func (*SyncMap[K, V]) Delete

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

Delete deletes the value for a key.

func (*SyncMap[K, V]) Load

func (m *SyncMap[K, V]) Load(key K) (value V, ok bool)

Load returns the value stored in the map for a key, or zero value if no value is present.

func (*SyncMap[K, V]) LoadAndDelete

func (m *SyncMap[K, V]) LoadAndDelete(key K) (value V, loaded bool)

LoadAndDelete deletes the value for a key, returning the previous value if any. The loaded result reports whether the key was present.

func (*SyncMap[K, V]) LoadOrStore

func (m *SyncMap[K, V]) LoadOrStore(key K, value V) (actual V, loaded bool)

LoadOrStore 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 (*SyncMap[K, V]) Range

func (m *SyncMap[K, V]) Range(f func(key K, value V) bool)

Range calls f sequentially for each key and value present in the map. If f returns false, range stops the iteration.

func (*SyncMap[K, V]) Store

func (m *SyncMap[K, V]) Store(key K, value V)

Store sets the value for a key.

func (*SyncMap[K, V]) Swap

func (m *SyncMap[K, V]) Swap(key K, value V) (previous V, loaded bool)

Swap swaps the value for a key and returns the previous value if any. The loaded result reports whether the key was present.