xcache

Documentation

Overview

Package xcache provides an in-memory LRU cache with extra features inspired from nginx caching. It is based on https://github.com/karlseguin/ccache for the basic caching features (LRU, concurrency optimizations).

It adds cache locking (prevents 2 concurrent fetches for the same item), infinite serving of stale values in case of fetch errors, asynchronous refresh of stale values, concurrency-limited refresh fetchers, and negative cache.

Its usage makes use of a single function Fetch() (no Get()/Set()), which is provided with a closure capturing the parameters necessary to fetch for the given key.

Index

• type Cache
  • func New(opts ...Option) (*Cache, error)
  • func (c *Cache) Fetch(key string, f Fetcher) (interface{}, error)
  • func (c *Cache) Hits() uint64
  • func (c *Cache) NewFetches() uint64
  • func (c *Cache) Requests() uint64
  • func (c *Cache) StaleFetches() uint64
• type Fetcher
• type Option
  • func WithFetchers(n int) Option
  • func WithNegPruneSize(n int32) Option
  • func WithNegSize(n int32) Option
  • func WithNegTTL(t time.Duration) Option
  • func WithPruneSize(n int32) Option
  • func WithSize(n int32) Option
  • func WithStale(useStale bool) Option
  • func WithStaleFetchers(n int) Option
  • func WithStaleQueueSize(n int) Option
  • func WithStaleValidator(f func(interface{}, time.Duration) bool) Option
  • func WithTTL(t time.Duration) Option

Types

type Cache

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

Cache is the type supporting the local caching of objects.

func New

func New(opts ...Option) (*Cache, error)

New builds a cache given some options.

func (*Cache) Fetch

func (c *Cache) Fetch(key string, f Fetcher) (interface{}, error)

Fetch returns an object given its cache key and a Fetcher function for fetching it if it expired or missing.

This function will usually be implemented as a closure in order to capture the various parameters needed for fetching from the backend the entry corresponding to the cache key.

Entries are first looked up in the positive cache, then negative, then fetched.

An asynchronous fetch will happen if the entry is stale.

func (*Cache) Hits

func (c *Cache) Hits() uint64

Hits returns the number of cache hits since start.

func (*Cache) NewFetches

func (c *Cache) NewFetches() uint64

NewFetches returns the number of fetches for items not in cache, since start.

func (*Cache) Requests

func (c *Cache) Requests() uint64

Requests returns the number of cache requests (hits and misses) since start.

func (*Cache) StaleFetches

func (c *Cache) StaleFetches() uint64

StaleFetches returns the number of fetches for expired items, since start.

type Fetcher

type Fetcher func() (interface{}, bool, error)

Fetcher is the type of the closure passed to Fetch() for fetching the desired object if missing or stale.

Depending on the boolean validity and error returned by the closure, the entry will end in the positive or the negative cache (and possibly removed from the other).

If non-nil error, entry will be stored in negative cache (but positive entry will be untouched - use this for transient backend failures); else if validity is false, will be stored in negative cache and positive entry will be deleted (use this case when the item is not "positive" anymore - has invalid state or has been removed); else (nil error nil and true validity) store in positive cache and remove neg entry

type Option

type Option func(c *Cache)

Option is the type of option passed to the constructor.

func WithFetchers

func WithFetchers(n int) Option

WithFetchers sets the max number of concurrent fetches. Default: 100

func WithNegPruneSize

func WithNegPruneSize(n int32) Option

WithNegPruneSize sets the number of entries to evict when the negative cache is full. Default: negSize/20

func WithNegSize

func WithNegSize(n int32) Option

WithNegSize sets the size of the negative cache, used for storing errors and invalid objects. Default: 500

func WithNegTTL

func WithNegTTL(t time.Duration) Option

WithNegTTL sets the duration of a negative cache entry. Default: 5 * time.Second

func WithPruneSize

func WithPruneSize(n int32) Option

WithPruneSize sets the number of entries to evict when the positive cache is full. Default: posSize/20

func WithSize

func WithSize(n int32) Option

WithSize sets the max cache size (in number of objets). When the cache is full, a portion of the least recently used objets will be evicted. Default: 5000

func WithStale

func WithStale(useStale bool) Option

WithStale allows to decide globally if expired items are served. If false, WithStaleValidator will be ignored. Default: true

func WithStaleFetchers

func WithStaleFetchers(n int) Option

WithStaleFetchers sets the number of fetchers in the pool for async fetch of stale entries. Default: 3

func WithStaleQueueSize

func WithStaleQueueSize(n int) Option

WithStaleQueueSize sets the size of the chan for queuing items. Default: 1000

func WithStaleValidator

func WithStaleValidator(f func(interface{}, time.Duration) bool) Option

WithStaleValidator allows to use a function to decide if a stale item will be served. The duration is the extra time after expiration. Default: nil (WithStale() will decide if stale items are served)

func WithTTL

func WithTTL(t time.Duration) Option

WithTTL sets the duration upon which an object will be deemed expired. In this case, a background refresh will occur. Default: 60 * time.Second