common

Documentation

Index

• Variables
• func AuthorizationError(detail string, args ...any) error
• func DoesNotExistError(detail string, args ...any) error
• func DuplicateEntryError(detail string, args ...any) error
• func Error(err error, detail string, args ...any) error
• func InvalidArgument(detail string, args ...any) error
• func IsError(err error, target error) bool
• func Must(err error)
• func MustReturn[T any](value T, err error) T
• func TooManyRequests(detail string, args ...any) error
• type AtomicReference
  • func NewAtomicReference[T any](init T) *AtomicReference[T]
  • func (ref *AtomicReference[T]) Load() T
  • func (ref *AtomicReference[T]) Store(value T)
  • func (ref *AtomicReference[T]) Swap(value T) T
• type CacheStore
• type Clock
  • func SystemTime() Clock
• type Entry
• type EntryState
  • func (state EntryState) String() string
• type LoadingCache
  • func NewLoadingCache[V any](store CacheStore[V]) *LoadingCache[V]
  • func (cache *LoadingCache[V]) Cancel(key string)
  • func (cache *LoadingCache[V]) Check(key string) bool
  • func (cache *LoadingCache[V]) Drop(key string)
  • func (cache *LoadingCache[V]) Get(key string) Value[V]
  • func (cache *LoadingCache[V]) Put(key string, loadingFunc func() (V, error)) error
  • func (cache *LoadingCache[V]) Refresh(key string) error
  • func (cache *LoadingCache[V]) Replace(key string, loadingFunc func() (V, error))
• type MapStore
  • func NewMapStore[V any]() MapStore[V]
  • func (store MapStore[V]) Delete(key string)
  • func (store MapStore[V]) Get(key string) *Entry[V]
  • func (store MapStore[V]) Put(key string, val *Entry[V])
• type StableClock
  • func StableTime(epoch time.Time) StableClock
• type TreeStore
  • func NewTreeStore[V any]() TreeStore[V]
  • func (store TreeStore[V]) Delete(key string)
  • func (store TreeStore[V]) Get(key string) *Entry[V]
  • func (store TreeStore[V]) Put(key string, val *Entry[V])
• type Value

Variables

var (
	ErrAccess    = errors.New("unauthorized")
	ErrExists    = errors.New("already exists")
	ErrNotExists = errors.New("does not exist")
	ErrCanceled  = errors.New("execution canceled")
	ErrInvalid   = errors.New("invalid argument")
	ErrLimit     = errors.New("too many requests")
)

Functions

func AuthorizationError

func AuthorizationError(detail string, args ...any) error

func DoesNotExistError

func DoesNotExistError(detail string, args ...any) error

func DuplicateEntryError

func DuplicateEntryError(detail string, args ...any) error

func Error

func Error(err error, detail string, args ...any) error

func InvalidArgument

func InvalidArgument(detail string, args ...any) error

func IsError

func IsError(err error, target error) bool

func Must

func Must(err error)

func MustReturn

func MustReturn[T any](value T, err error) T

func TooManyRequests

func TooManyRequests(detail string, args ...any) error

Types

type AtomicReference

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

AtomicReference is a Generic wrapper for atomic.Value

func NewAtomicReference

func NewAtomicReference[T any](init T) *AtomicReference[T]

NewAtomicReference returns a new AtomicReference with an initial value.

func (*AtomicReference[T]) Load

func (ref *AtomicReference[T]) Load() T

Load wraps atomic.Load

func (*AtomicReference[T]) Store

func (ref *AtomicReference[T]) Store(value T)

Store wraps atomic.Store

func (*AtomicReference[T]) Swap

func (ref *AtomicReference[T]) Swap(value T) T

Swap wraps atomic.Swap

type CacheStore

type CacheStore[V any] interface {
	Get(string) *Entry[V]
	Put(string, *Entry[V])
	Delete(string)
}

type Clock

type Clock interface {
	// Now returns the current clock time.
	Now() time.Time
	// In returns the clock time plus time.Duration
	In(time.Duration) time.Time
}

func SystemTime

func SystemTime() Clock

SystemTime is a clock facade on time.Time.

type Entry

type Entry[V any] struct {
	// contains filtered or unexported fields
}

Entry represents a cached entry.

type EntryState

type EntryState uint8

EntryState represents the current state of a CacheEntry.

const (
	// EntryInit marks a cache entry as initialized but not yet populated.
	EntryInit EntryState = iota
	// EntryPending indicates the cache entry is the process of being updated.
	EntryPending
	// EntryError indicates the last attempt to update a cache entry failed.
	EntryError
	// EntryCanceled indicates an update was attempted but canceled before completing.
	EntryCanceled
	// EntryReady indicates the cache entry is ready for use.
	EntryReady
)

func (EntryState) String

func (state EntryState) String() string

String returns EntryState as a string.

type LoadingCache

type LoadingCache[V any] struct {
	// contains filtered or unexported fields
}

LoadingCache is an in-memory key-value store. Value lifecycles are managed by the cache until their key is dropped.

func NewLoadingCache

func NewLoadingCache[V any](store CacheStore[V]) *LoadingCache[V]

NewLoadingCache returns a new instance of LoadingCache[V].

func (*LoadingCache[V]) Cancel

func (cache *LoadingCache[V]) Cancel(key string)

Cancel cancels an update and notifies all watchers.

func (*LoadingCache[V]) Check

func (cache *LoadingCache[V]) Check(key string) bool

Check returns true if a key is present in the cache, else false.

func (*LoadingCache[V]) Drop

func (cache *LoadingCache[V]) Drop(key string)

Drop removes the entry associated with key from the cache.

func (*LoadingCache[V]) Get

func (cache *LoadingCache[V]) Get(key string) Value[V]

Get the Entry associated with Key, loading a new instance if unknown. If Entry exists and is EntryPending this call parks the caller until the update is complete.

func (*LoadingCache[V]) Put

func (cache *LoadingCache[V]) Put(key string, loadingFunc func() (V, error)) error

Put creates a new entry in the LoadingCache using the supplied loadingFunc. All entries are loaded lazily meaning loadingFunc is not invoked until LoadingCache.Get(key) is called.

func (*LoadingCache[V]) Refresh

func (cache *LoadingCache[V]) Refresh(key string) error

Refresh updates a cache Entry asynchronously. Calling LoadingCache.Get(key) immediately allows the caller to await the result.

func (*LoadingCache[V]) Replace

func (cache *LoadingCache[V]) Replace(key string, loadingFunc func() (V, error))

Replace overwrites the loadingFunc for an existing key. If there is no key present a new one will be created.

type MapStore

type MapStore[V any] struct {
	// contains filtered or unexported fields
}

func NewMapStore

func NewMapStore[V any]() MapStore[V]

func (MapStore[V]) Delete

func (store MapStore[V]) Delete(key string)

func (MapStore[V]) Get

func (store MapStore[V]) Get(key string) *Entry[V]

func (MapStore[V]) Put

func (store MapStore[V]) Put(key string, val *Entry[V])

type StableClock

type StableClock interface {
	Clock
	// Tick increments StableTime by duration
	Tick(duration time.Duration)
}

func StableTime

func StableTime(epoch time.Time) StableClock

StableTime is a clock which must be manually updated.

type TreeStore

type TreeStore[V any] struct {
	// contains filtered or unexported fields
}

func NewTreeStore

func NewTreeStore[V any]() TreeStore[V]

func (TreeStore[V]) Delete

func (store TreeStore[V]) Delete(key string)

func (TreeStore[V]) Get

func (store TreeStore[V]) Get(key string) *Entry[V]

func (TreeStore[V]) Put

func (store TreeStore[V]) Put(key string, val *Entry[V])

type Value

type Value[V any] struct {
	State EntryState
	Value V
	Error error
}

Value is an immutable snapshot of a CacheEntry's state.