layered

Documentation

Overview

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

Index

• Variables
• type Cache
  • func (c *Cache) GetOrCreate(ctx context.Context, key string, fn lru.Maker, opts ...Option) (interface{}, error)
• type Option
  • func WithMinTTL(ttl time.Duration) Option
  • func WithRandomizedExpiration(threshold time.Duration) Option

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 struct {
	// ProcessLRUCache is a handle to a process LRU cache that holds the data.
	ProcessLRUCache caching.LRUHandle
	// GlobalNamespace is a global cache namespace to use for the data.
	GlobalNamespace string
	// Marshal converts an item being cached to a byte blob.
	Marshal func(item interface{}) ([]byte, error)
	// Unmarshal takes output of Marshal and converts it to an item to return.
	Unmarshal func(blob []byte) (interface{}, error)
}

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 (*Cache) GetOrCreate

func (c *Cache) GetOrCreate(ctx context.Context, key string, fn lru.Maker, opts ...Option) (interface{}, 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.

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.