cache

Documentation

Index

• Constants
• Variables
• type Cache
  • func NewNoop() Cache
• type CachedError
  • func (e CachedError) As(target interface{}) bool
  • func (e CachedError) Error() string
  • func (e CachedError) Unwrap() error
• type LRU
  • func NewLRU(opts *LRUOptions) *LRU
  • func (c *LRU) Get(ctx context.Context, key string, loader LoaderFunc) (interface{}, error)
  • func (c *LRU) GetWithTTL(ctx context.Context, key string, loader LoaderWithTTLFunc) (interface{}, error)
  • func (c *LRU) Put(key string, value interface{})
  • func (c *LRU) PutWithTTL(key string, value interface{}, ttl time.Duration)
  • func (c *LRU) TryGet(key string) (interface{}, bool)
• type LRUOptions
• type LoaderFunc
• type LoaderWithTTLFunc
• type UncachedError
  • func (e UncachedError) As(target interface{}) bool
  • func (e UncachedError) Error() string
  • func (e UncachedError) Unwrap() error

Constants

const (
	DefaultTTL        = time.Minute * 30
	DefaultMaxEntries = 10000
)

Defaults for use with the LRU cache.

Variables

var (
	// ErrEntryNotFound is returned if a cache entry cannot be found.
	ErrEntryNotFound = status.Error(codes.NotFound, "not found")

	// ErrCacheFull is returned if we need to load an entry, but the cache is already full of entries that are loading.
	ErrCacheFull = status.Error(codes.ResourceExhausted, "try again later")
)

Types

type Cache

type Cache interface {
	// Put puts a new item in the cache with the default TTL.
	Put(key string, value interface{})

	// PutWithTTL puts a new item in the cache with a specific TTL.
	PutWithTTL(key string, value interface{}, ttl time.Duration)

	// Get returns the value associated with the key, optionally
	// loading it if it does not exist or has expired.
	// NB(mmihic): We pass the loader as an argument rather than
	// making it a property of the cache to support access specific
	// loading arguments which might not be bundled into the key.
	Get(ctx context.Context, key string, loader LoaderFunc) (interface{}, error)

	// GetWithTTL returns the value associated with the key, optionally
	// loading it if it does not exist or has expired, and allowing the
	// loader to return a TTL for the resulting value, overriding the
	// default TTL associated with the cache.
	GetWithTTL(ctx context.Context, key string, loader LoaderWithTTLFunc) (interface{}, error)
}

Cache is an interface for caches.

func NewNoop

func NewNoop() Cache

NewNoop returns a new no-op cache.

type CachedError

type CachedError struct {
	Err error
}

CachedError is a wrapper that can be used to force an error to be cached. Useful when you want to opt-in to error caching. The underlying error will be unwrapped before returning to the caller.

func (CachedError) As

func (e CachedError) As(target interface{}) bool

As returns true if the caller is asking for the error as an cached error

func (CachedError) Error

func (e CachedError) Error() string

Error returns the message for the underlying error

func (CachedError) Unwrap

func (e CachedError) Unwrap() error

Unwrap unwraps the underlying error

type LRU

type LRU struct {
	// contains filtered or unexported fields
}

LRU is a fixed size LRU cache supporting expiration, loading of entries that do not exist, ability to cache negative results (e.g errors from load), and a mechanism for preventing multiple goroutines from entering the loader function simultaneously for the same key, and a mechanism for restricting the amount of total concurrency in the loader function.

func NewLRU

func NewLRU(opts *LRUOptions) *LRU

NewLRU returns a new LRU with the provided options.

func (*LRU) Get

func (c *LRU) Get(ctx context.Context, key string, loader LoaderFunc) (interface{}, error)

Get returns the value associated with the key, optionally loading it if it does not exist or has expired. NB(mmihic): We pass the loader as an argument rather than making it a property of the cache to support access specific loading arguments which might not be bundled into the key.

func (*LRU) GetWithTTL

func (c *LRU) GetWithTTL(ctx context.Context, key string, loader LoaderWithTTLFunc) (interface{}, error)

GetWithTTL returns the value associated with the key, optionally loading it if it does not exist or has expired, and allowing the loader to return a TTL for the resulting value, overriding the default TTL associated with the cache.

func (*LRU) Put

func (c *LRU) Put(key string, value interface{})

Put puts a value directly into the cache. Uses the default TTL.

func (*LRU) PutWithTTL

func (c *LRU) PutWithTTL(key string, value interface{}, ttl time.Duration)

PutWithTTL puts a value directly into the cache with a custom TTL.

func (*LRU) TryGet

func (c *LRU) TryGet(key string) (interface{}, bool)

TryGet will simply attempt to get a key and if it does not exist and instead of loading it if it is missing it will just return the second boolean argument as false to indicate it is missing.

type LRUOptions

type LRUOptions struct {
	TTL                  time.Duration
	InitialSize          int
	MaxEntries           int
	MaxConcurrency       int
	CacheErrorsByDefault bool
	Metrics              tally.Scope
	Now                  func() time.Time
}

LRUOptions are the options to an LRU cache.

type LoaderFunc

type LoaderFunc func(ctx context.Context, key string) (interface{}, error)

A LoaderFunc is a function for loading entries from a cache.

type LoaderWithTTLFunc

type LoaderWithTTLFunc func(ctx context.Context, key string) (interface{}, time.Time, error)

A LoaderWithTTLFunc is a function for loading entries from a cache, also returning an expiration time.

type UncachedError

type UncachedError struct {
	Err error
}

An UncachedError can be used to wrap an error that should not be cached, even if the cache is caching errors. The underlying error will be unwrapped before returning to the caller.

func (UncachedError) As

func (e UncachedError) As(target interface{}) bool

As returns true if the caller is asking for the error as an uncached error

func (UncachedError) Error

func (e UncachedError) Error() string

Error returns the message for the underlying error

func (UncachedError) Unwrap

func (e UncachedError) Unwrap() error

Unwrap unwraps the underlying error