adt

package
v0.10.9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 14, 2024 License: Apache-2.0 Imports: 12 Imported by: 14

Documentation

Overview

Package adt provides "atomic data types" as strongly-typed generic helpers for simple atomic operations (including sync.Map, sync.Pool, and a typed value).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AccessorsWithLock added in v0.10.5 

func AccessorsWithLock[T any](getter fun.Future[T], setter fun.Handler[T]) (fun.Future[T], fun.Handler[T])

AccessorsWithLock takes a getter/setter pair and configures both with a shared mutex: all read/write operations are fully synchronized with regards to eachother.

func AccessorsWithReadLock added in v0.10.5 

func AccessorsWithReadLock[T any](getter fun.Future[T], setter fun.Handler[T]) (fun.Future[T], fun.Handler[T])

AccessorsWithReadLock takes a getter/setter pair and configures them with a rw-mutex: the getter (Future) uses the read lock, while the setter is write-locked.

func CompareAndSwap 

func CompareAndSwap[T comparable, A AtomicValue[T]](a A, old, new T) bool

CompareAndSwap exposes the CompareAndSwap option for atomics that store values of comparable types. Only supports the Atomic and Synchronized types, as well as any type that implement a CompareAndSwap method for old/new values of T. Panics for all other types.

func Lock added in v0.10.0 

func Lock(mtx *sync.Mutex) *sync.Mutex

Lock takes the lock, locks it, and then returns it.

This, in combination With() makes it possible to have a single statement for managing a mutex in a defer, given the evaluation time of defer arguments, as in: 

mtx := &sync.Mutex{}
defer adt.With(adt.Lock(mtx))

func Mnemonize added in v0.9.0 

func Mnemonize[T any](in func() T) func() T

Mnemonize, like adt.Once, provides a way to lazily resolve and cache a value. Mnemonize takes an input function that returns a type and returns a function of the same signature. When the function is called the first time it caches the value and returns it henceforth.

While the function produced by Mnemonize is safe to use concurrently, there is no provision for protecting mutable types returned by the function and concurrent modification of mutable returned values is a race.

func Reset added in v0.10.2 

func Reset[T intish.Numbers, A AtomicValue[T]](a A) T

Reset, for an atomic value that holds a number, sets the atomic to 0, and returns the previously stored value.

func SafeSet 

func SafeSet[T comparable, A AtomicValue[T]](atom A, value T)

SafeSet sets the atomic to the given value only if the value is not the Zero value for that type.

func With added in v0.10.0 

func With(mtx *sync.Mutex)

With takes a lock as an argument and then releases the lock when it executes.

This, in combination with Lock makes it possible to have a single statement for managing a mutex in a defer, given the evaluation time of defer arguments, as in: 

mtx := &sync.Mutex{}
defer adt.With(adt.Lock(mtx))

Types

type Atomic 

type Atomic[T any] struct {
	// contains filtered or unexported fields
}

Atomic is a very simple atomic Get/Set operation, providing a generic type-safe implementation wrapping sync/atomic.Value. The primary caveat is that interface types are not compatible with adt.Atomic as a result of the standard library's underlying atomic type. To store interface objects atomically you can wrap the object in a function, using ft.Wrapper.

func NewAtomic 

func NewAtomic[T any](initial T) *Atomic[T]

NewAtomic creates a new Atomic Get/Set value with the initial value already set. This is a helper for creating a new atomic with a default value set.

func (*Atomic[T]) Get 

func (a *Atomic[T]) Get() T

Get resolves the atomic value, returning the zero value of the type T if the value is unset.

func (*Atomic[T]) Load added in v0.10.2 

func (a *Atomic[T]) Load() T

Load returns the value stored in the atomic. It mirrors the standard library's interface for atomics.

func (*Atomic[T]) Set 

func (a *Atomic[T]) Set(in T)

Set atomically sets the value of the Atomic.

func (*Atomic[T]) Store added in v0.10.2 

func (a *Atomic[T]) Store(in T)

Store saves the value in the atomic.

func (*Atomic[T]) Swap 

func (a *Atomic[T]) Swap(new T) (old T)

Swap does an in place exchange of the contents of a value exchanging the new value for the old. Unlike sync.Atomic.Swap() if new is nil, adt.Atomic.Swap() does NOT panic, and instead constructs the zero value of type T.

type AtomicValue added in v0.9.0 

type AtomicValue[T any] interface {
	Load() T
	Store(T)
	Swap(T) T
}

AtomicValue describes the public interface of the Atomic type. Use this definition to compose atomic types into other interfaces.

type Map 

type Map[K comparable, V any] struct {
	// Default handles construction and pools objects in
	// the map for the Ensure and Get operations which must
	// construct zero-value items. No configuration or
	// construction is necessary; however, callers can modify the
	// default value constructed as needed.
	Default Pool[V]
	// contains filtered or unexported fields
}

Map provides a wrapper around the standard library's sync.Map type with key/value types enforced by generics. Additional helpers support adding multiple items to the map, while Iterator and StoreFrom provide compatibility with iterators.

func (*Map[K, V]) Check added in v0.10.0 

func (mp *Map[K, V]) Check(key K) bool

Check returns true if the key exists in the map or false otherwise.

func (*Map[K, V]) Delete 

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

Delete removes a key--and its corresponding value--from the map, if it exists.

func (*Map[K, V]) Ensure 

func (mp *Map[K, V]) Ensure(key K)

Ensure adds a key to the map if it does not already exist, using the default value. The default value, is taken from the pool, which has a configurable constructor if you want a different default value.

func (*Map[K, V]) EnsureDefault 

func (mp *Map[K, V]) EnsureDefault(key K, constr func() V) V

EnsureDefault is similar to EnsureStore and Ensure, but provides the default value as a function that produces a value rather than the value directly. The returned value is *always* the value of the key, which is either the value from the map or the value produced by the function.

The constructor function is *always* called, even when the key exists in the map. Unlike Get and Ensure which have similar semantics and roles, the value produced by function does not participate in the default object pool.

func (*Map[K, V]) EnsureSet added in v0.8.5 

func (mp *Map[K, V]) EnsureSet(i dt.Pair[K, V]) bool

EnsureSet has the same semantics as EnsureStore, but takes a dt.Pair object.

func (*Map[K, V]) EnsureStore added in v0.8.5 

func (mp *Map[K, V]) EnsureStore(k K, v V) bool

Ensure store takes a value and returns true if the value was stored in the map.

func (*Map[K, V]) Get 

func (mp *Map[K, V]) Get(key K) V

Get retrieves the value from the map at the given value. If the key is not present in the map a default value is created and added to the map.

func (*Map[K, V]) Iterator 

func (mp *Map[K, V]) Iterator() *fun.Iterator[dt.Pair[K, V]]

Iterator returns an iterator that produces a sequence of pair objects.

This operation relies on a the underlying Range iterator, and advances lazily through the Range operation as callers advance the iterator. Be aware that this produces an iterator that does not reflect any particular atomic of the underlying map.

func (*Map[K, V]) Keys added in v0.8.5 

func (mp *Map[K, V]) Keys() *fun.Iterator[K]

Keys returns an iterator that renders all of the keys in the map.

This operation relies on a the underlying Range iterator, and advances lazily through the Range operation as callers advance the iterator. Be aware that this produces an iterator that does not reflect any particular atomic of the underlying map.

func (*Map[K, V]) Len 

func (mp *Map[K, V]) Len() int

Len counts and reports on the number of items in the map. This is provided by iterating and counting the values in the map, and has O(n) performance.

Len uses a range function and therefore does not reflect a specific snapshot of the map at any time if keys are being deleted while Len is running. Len will never report a number that is larger than the total number of items in the map while Len is running, but the number of items in the map may be smaller at the beginning and/or the end than reported.

func (*Map[K, V]) Load 

func (mp *Map[K, V]) Load(key K) (V, bool)

Load retrieves the value from the map. The semantics are the same as for maps in go: if the value does not exist it always returns the zero value for the type, while the second value indicates if the key was present in the map.

func (*Map[K, V]) MarshalJSON 

func (mp *Map[K, V]) MarshalJSON() ([]byte, error)

MarshalJSON produces a JSON form of the map, using a Range function to iterate through the values in the map. Range functions do not reflect a specific snapshot of the map if the map is being modified while being marshaled: keys will only appear at most once but order or which version of a value is not defined.

func (*Map[K, V]) Range 

func (mp *Map[K, V]) Range(fn func(K, V) bool)

Range provides a method for iterating over the values in the map, with a similar API as the standard library's sync.Map. The function is called once on every key in the map. When the range function returns false the iteration stops.

Range functions do not reflect a specific snapshot of the map if the map is being modified while being marshaled: keys will only appear at most once but order or which version of a value is not defined.

func (*Map[K, V]) Set 

func (mp *Map[K, V]) Set(it dt.Pair[K, V])

Set adds a key and value to the map from a Pair.

func (*Map[K, V]) Store 

func (mp *Map[K, V]) Store(k K, v V)

Store adds a key and value to the map, replacing any existing values as needed.

func (*Map[K, V]) Swap 

func (mp *Map[K, V]) Swap(k K, v V) (V, bool)

func (*Map[K, V]) UnmarshalJSON 

func (mp *Map[K, V]) UnmarshalJSON(in []byte) error

UnmarshalJSON takes a json sequence and adds the values to the map. This does not remove or reset the values in the map, and other operations may interleave during this operation.

func (*Map[K, V]) Values added in v0.8.5 

func (mp *Map[K, V]) Values() *fun.Iterator[V]

Values returns an iterator that renders all of the values in the map.

This operation relies on a the underlying Range iterator, and advances lazily through the Range operation as callers advance the iterator. Be aware that this produces an iterator that does not reflect any particular atomic of the underlying map.

type Once added in v0.9.0 

type Once[T any] struct {
	// contains filtered or unexported fields
}

Once provides a mnemonic form of sync.Once, caching and returning a value after the Do() function is called.

func NewOnce added in v0.10.0 

func NewOnce[T any](fn func() T) *Once[T]

NewOnce creates a Once object and initializes it with the function provided. This is optional and this function can be later overridden by Set() or Do(). When the operation is complete, the Once operation has been

func (*Once[T]) Called added in v0.10.0 

func (o *Once[T]) Called() bool

Called returns true if the Once object has been called or is currently running, and false otherwise.

func (*Once[T]) Defined added in v0.10.0 

func (o *Once[T]) Defined() bool

Defined returns true when the function has been set. Use only for observational purpsoses. Though the value is stored in an atomic, it does reflect the state of the underlying operation.

func (*Once[T]) Do added in v0.9.0 

func (o *Once[T]) Do(ctor func() T)

Do runs the function provided, and caches the results. All subsequent calls to Do or Resolve() are noops. If multiple callers use Do/Resolve at the same time, like sync.Once.Do none will return until return until the first operation completes.

Functions passed to Do should return values that are safe for concurrent access: while the Do/Resolve operations are synchronized, the return value from Do is responsible for its own synchronization.

func (*Once[T]) Resolve added in v0.10.0 

func (o *Once[T]) Resolve() T

Resolve runs the stored, if and only if it hasn't been run function and returns its output. Once the function has run, Resolve will continue to return the cached value.

func (*Once[T]) Set added in v0.10.0 

func (o *Once[T]) Set(constr func() T)

Set sets the constrctor/operation for the Once object, but does not execute the operation. The operation is atomic, is a noop after the operation has completed, will not reset the operation or the cached value.

type Pool 

type Pool[T any] struct {
	// contains filtered or unexported fields
}

Pool is an ergonomic wrapper around sync.Pool that provides some additional functionality: generic type interface, a default clean up hook to modify (optionally) the object before returning it to the pool.

Additionally, the Make() method attaches an object finalizer to the object produced by the pool that returns the object to the pool rather than garbage collect it. This is likely to be less efficient than return the objects to the pool using defer functions, but may be more ergonomic in some situations.

Pool can be used with default construction; however, you should set the Constructor before calling Get() or Make() on the pool.

func DefaultBufferPool added in v0.10.4 

func DefaultBufferPool() *Pool[dt.Slice[byte]]

DefaultBufferPool creates a pool of byte slices with a maximum size of 64kb. All other slices are discarded. These are the same settings as used by the fmt package's buffer pool.

The type of the pooled object is dt.Slice[byte], a simple type alias for Go's slice type with convenience methods for common slice operations. You can use these values interchangeably with vanilla byte slices, as you need and wish.

func MakeBufferPool added in v0.10.4 

func MakeBufferPool(min, max int) *Pool[dt.Slice[byte]]

MakeBufferPool constructs a pool of byte slices. New slices are allocated with the specified minimum capacity, and are always resliced to be 0 length before reentering the pool. Slices that are larger than the specified maximum do not reenter the pool.

Min/Max values less than 0 are ignored, and the highest value is always used as the max the lowest as the min, regardless of position. MakeBufferPool panics with an invariant violation if the max capacity value is zero.

The type of the pooled object is dt.Slice[byte], a simple type alias for Go's slice type with convenience methods for common slice operations. You can use these values interchangeably with vanilla byte slices, as you need and wish.

func MakeBytesBufferPool added in v0.10.4 

func MakeBytesBufferPool(capacity int) *Pool[*bytes.Buffer]

MakeBytesBufferPool configures a pool of *bytes.Buffers. Buffers are always reset before reentering the pool, and are pre-allocated with the specified capacity. Negative initial capcity values are ignored.

func (*Pool[T]) FinalizeSetup added in v0.10.4 

func (p *Pool[T]) FinalizeSetup()

FinalizeSetup prevents future calls from setting the constructor or cleanup hooks. Once a pool's setup has been finalized it cannot be unset: future attempts to set the constructor or cleanup hook result in a panic and invariant violation. FinalizeSetup is safe to cull multiple times and from different go routines.

func (*Pool[T]) Get 

func (p *Pool[T]) Get() T

Get returns an object from the pool or constructs a default object according to the constructor.

func (*Pool[T]) Make 

func (p *Pool[T]) Make() T

Make gets an object out of the sync.Pool, and attaches a finalizer that returns the item to the pool when the object would be garbage collected.

Finalizer hooks are not automatically cleared by the Put() operation, so objects retrieved with Make should not be passed manually to Put().

func (*Pool[T]) Put 

func (p *Pool[T]) Put(in T)

Put returns an object in the pool, calling the cleanuphook if set. Put *always* clears the object's finalizer before calling the cleanuphook or returning it to the pool.

func (*Pool[T]) SetCleanupHook 

func (p *Pool[T]) SetCleanupHook(in func(T) T)

SetCleanupHook sets a function to be called on every object renetering the pool. By default, the cleanup function is a noop, and if the input function is nil, it is not set.

func (*Pool[T]) SetConstructor 

func (p *Pool[T]) SetConstructor(in func() T)

SetConstructor overrides the default constructor (which makes an object with a Zero value by default) for Get/Make operations.

type Synchronized added in v0.8.7 

type Synchronized[T any] struct {
	// contains filtered or unexported fields
}

Synchronized wraps an arbitrary type with a lock, and provides a functional interface for interacting with that type. In general Synchronize is ideal for container and interface types which are not safe for concurrent use, when either `adt.Map`, `adt.Atomic` are not appropriate.

func NewSynchronized added in v0.8.7 

func NewSynchronized[T any](in T) *Synchronized[T]

NewSynchronized constructs a new synchronized object that wraps the input type.

func (*Synchronized[T]) Get added in v0.8.9 

func (s *Synchronized[T]) Get() T

Get returns the underlying protected object. Use with caution.

func (*Synchronized[T]) Load added in v0.10.2 

func (s *Synchronized[T]) Load() T

func (*Synchronized[T]) Set added in v0.8.7 

func (s *Synchronized[T]) Set(in T)

Set overrides the current value of the protected object. Use with caution.

func (*Synchronized[T]) Store added in v0.10.2 

func (s *Synchronized[T]) Store(in T)

func (*Synchronized[T]) String added in v0.8.9 

func (s *Synchronized[T]) String() string

String implements fmt.Stringer using this type.

func (*Synchronized[T]) Swap added in v0.8.9 

func (s *Synchronized[T]) Swap(new T) (old T)

Swap sets the locked value to the new value and returns the old.

func (*Synchronized[T]) Using added in v0.10.0 

func (s *Synchronized[T]) Using(op func())

Using runs the provided operation while holding the lock, but without providing access to the locked value.

func (*Synchronized[T]) With added in v0.8.7 

func (s *Synchronized[T]) With(in func(obj T))

With runs the input function within the lock, to mutate the object.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.