layered

Documentation

Overview

Package layered provides a two-layer cache for serializable objects.

Index

• Variables
• type Cache
  • func RegisterCache[T any](p Parameters[T]) Cache[T]
  • func (c *Cache[T]) CachedLocally(ctx context.Context) int
  • func (c *Cache[T]) GetOrCreate(ctx context.Context, key string, fn lru.Maker[T], opts ...Option) (T, error)
  • func (c *Cache[T]) Parameters() Parameters[T]
• type Option
  • func WithMinTTL(ttl time.Duration) Option
  • func WithRandomizedExpiration(threshold time.Duration) Option
• type Parameters

Variables

var ErrCantSatisfyMinTTL = errors.New("new item produced by the factory has insufficient TTL")

ErrCantSatisfyMinTTL is returned by GetOrCreate if the factory function produces an item that expires sooner than the requested MinTTL.

Types

type Cache

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

Cache implements a cache of serializable objects on top of process and global caches.

If the global cache is not available or fails, degrades to using only process cache.

Since global cache errors are ignored, gives no guarantees of consistency or item uniqueness. Thus supposed to be used only when caching results of computations without side effects.

func RegisterCache

func RegisterCache[T any](p Parameters[T]) Cache[T]

RegisterCache registers a layered cache used by a process.

It must be called during init time to declare an intent that a package wants to use an LRU cache. The actual local cache itself will be stored in ProcessCacheData inside a context, see caching.RegisterLRUCache.

func (*Cache[T]) CachedLocally

func (c *Cache[T]) CachedLocally(ctx context.Context) int

CachedLocally returns the number of items stored in the local process memory.

func (*Cache[T]) GetOrCreate

func (c *Cache[T]) GetOrCreate(ctx context.Context, key string, fn lru.Maker[T], opts ...Option) (T, error)

GetOrCreate attempts to grab an item from process or global cache, or create it if it's not cached yet.

Fetching an item from the global cache or instantiating a new item happens under a per-key lock.

Expiration time is used with seconds precision. Zero expiration time means the item doesn't expire on its own.

func (*Cache[T]) Parameters

func (c *Cache[T]) Parameters() Parameters[T]

Parameters returns the parameters the cache was created with.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option is a base interface of options for GetOrCreate call.

func WithMinTTL

func WithMinTTL(ttl time.Duration) Option

WithMinTTL specifies minimal acceptable TTL (Time To Live) of the returned cached item.

If the currently cached item expires sooner than the requested TTL, it will be forcefully refreshed. If the new (refreshed) item also expires sooner than the requested min TTL, GetOrCreate will return ErrCantSatisfyMinTTL.

func WithRandomizedExpiration

func WithRandomizedExpiration(threshold time.Duration) Option

WithRandomizedExpiration enables randomized early expiration.

This is only useful if cached items are used highly concurrently from many goroutines.

On each cache access if the remaining TTL of the cached item is less than 'threshold', it may randomly be considered already expired (with probability increasing when item nears its true expiration).

This is useful to avoid a situation when many concurrent consumers discover at the same time that the item has expired, and then all proceed waiting for a refresh. With randomized early expiration only the most unlucky consumer will trigger the refresh and will be blocked on it.

type Parameters

type Parameters[T any] struct {
	// ProcessCacheCapacity is a maximum number of items to keep in the process
	// memory.
	//
	// If 0, will be unlimited.
	ProcessCacheCapacity int

	// GlobalNamespace is a global cache namespace to use for the data.
	//
	// Must be set.
	GlobalNamespace string

	// Marshal converts an item being cached to a byte blob.
	//
	// Must be set.
	Marshal func(item T) ([]byte, error)

	// Unmarshal takes output of Marshal and converts it to an item to return.
	//
	// Must be set.
	Unmarshal func(blob []byte) (T, error)

	// AllowNoProcessCacheFallback is true to allow bypassing all the caching if
	// the process cache is not configured (which often happens in tests).
	//
	// When the process cache is not available, if AllowNoProcessCacheFallback is
	// true, GetOrCreate would just always call the supplied callback to create
	// the item. If AllowNoProcessCacheFallback is false, it would instead
	// return caching.ErrNoProcessCache.
	AllowNoProcessCacheFallback bool
}

Parameters describes parameters of a layered cache.