cache

README

go-cache

Cache structs for Go

Basic cache

Basic implements Interface that stores an unlimited number of items. It has no eviction policy removal of expired items is the responsibility of the user (via Basic#Trim(time.Time)).

Documentation

Index

• Constants
• Variables
• func Exp(ttl time.Duration) *time.Time
• func Never() *time.Time
• type Cache
  • func New(size int) *Cache
  • func (c *Cache) Evict(keys ...interface{}) (size int)
  • func (c *Cache) Get(k interface{}) (v interface{}, exp *time.Time, err error)
  • func (c *Cache) Metrics() (m Metrics)
  • func (c *Cache) Set(k, v interface{}, exp *time.Time) error
  • func (c *Cache) Size() int
  • func (c *Cache) Trim(now time.Time) []interface{}
• type EvictionPolicy
• type FIFO
  • func NewFIFO(size int) *FIFO
  • func (c *FIFO) Evict(keys ...interface{}) int
  • func (c *FIFO) Get(k interface{}) (v interface{}, exp *time.Time, err error)
  • func (c *FIFO) Metrics() Metrics
  • func (c *FIFO) Set(k, v interface{}, exp *time.Time) (err error)
  • func (c *FIFO) Trim(now time.Time) []interface{}
• type Interface
  • func NewCache(size int, policy EvictionPolicy) Interface
• type LFU
  • func NewLFU(size int) *LFU
  • func (c *LFU) Evict(keys ...interface{}) int
  • func (c *LFU) Flush()
  • func (c *LFU) Get(x interface{}) (y interface{}, exp *time.Time, err error)
  • func (c *LFU) Metrics() Metrics
  • func (c *LFU) Set(x, y interface{}, exp *time.Time) (err error)
  • func (c *LFU) Trim(now time.Time) []interface{}
• type LRU
  • func NewLRU(size int) *LRU
  • func (c *LRU) Evict(keys ...interface{}) int
  • func (c *LRU) Flush()
  • func (c *LRU) Get(x interface{}) (y interface{}, exp *time.Time, err error)
  • func (c *LRU) Metrics() Metrics
  • func (c *LRU) Set(x, y interface{}, exp *time.Time) (err error)
  • func (c *LRU) Trim(now time.Time) []interface{}
• type Metrics
• type Upstream
  • func Blocking(up Upstream) Upstream
  • func Proxy(u Upstream, c Interface) Upstream
• type UpstreamFunc
  • func (f UpstreamFunc) Get(x interface{}) (y interface{}, exp *time.Time, err error)

Constants

const DefaultLFUQueueSize = 100

const DefaultLRUQueueSize = 100

Variables

var (
	// KeyError is returned by Get if a key is not found in the cache.
	KeyError     = errors.New("Key not found.")
	ExpiredError = errors.New("Key expired.")
	// MaxSizeError is returned by Set on implementations of Interface that have max size limits.
	MaxSizeError = errors.New("Cache full.")
)

Functions

func Exp

func Exp(ttl time.Duration) *time.Time

func Never

func Never() *time.Time

Never is a helper that returns a nil expiration time.

Types

type Cache

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

Cache implements Interface. Removal of expired items is the responsibility of the caller.

func New

func New(size int) *Cache

New returns a new Cache. size determines the maximum number of items the cache can hold. If set to zero or less the cache will not have a size limit.

func (*Cache) Evict

func (c *Cache) Evict(keys ...interface{}) (size int)

Evict removes items from the cache. It returns the new cache size.

func (*Cache) Get

func (c *Cache) Get(k interface{}) (v interface{}, exp *time.Time, err error)

Get returns a value assigned to a key and it's expiration time. If a key does not exist in cache KeyError is returned. If a key is expired ExpiredError is returned

func (*Cache) Metrics

func (c *Cache) Metrics() (m Metrics)

func (*Cache) Set

func (c *Cache) Set(k, v interface{}, exp *time.Time) error

Set assigns a value to a key and sets the expiration time If the size limit is reached it returns MaxSizeError.

func (*Cache) Size

func (c *Cache) Size() int

Size returns size of all keys in cache both expired and fresh

func (*Cache) Trim

func (c *Cache) Trim(now time.Time) []interface{}

Trim removes all expired keys and returns a slice of removed keys

type EvictionPolicy

type EvictionPolicy int

const (
	PolicyNone EvictionPolicy = iota
	PolicyFIFO
	PolicyLRU
	PolicyLFU
)

type FIFO

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

FIFO implements Interface with a first-in-first-out eviction policy.

func NewFIFO

func NewFIFO(size int) *FIFO

func (*FIFO) Evict

func (c *FIFO) Evict(keys ...interface{}) int

func (*FIFO) Get

func (c *FIFO) Get(k interface{}) (v interface{}, exp *time.Time, err error)

func (*FIFO) Metrics

func (c *FIFO) Metrics() Metrics

func (*FIFO) Set

func (c *FIFO) Set(k, v interface{}, exp *time.Time) (err error)

Set assigns a value to a key and sets the expiration time. If the size limit is reached the oldest item stored is evicted to insert the new one

func (*FIFO) Trim

func (c *FIFO) Trim(now time.Time) []interface{}

type Interface

type Interface interface {
	// Interface implements Upstream and returns KeyError if a key is not found in cache.
	Upstream
	// Set assigns a value to a key and sets the expiration time
	Set(key, value interface{}, exp *time.Time) error
	// Evict drops the provided keys from cache (if they exist) and returns the new size of the cache.
	// Calling Evict without arguments returns the current cache size.
	Evict(keys ...interface{}) (size int)
	Metrics() Metrics
}

Interface is the common cache interface for all implementations.

func NewCache

func NewCache(size int, policy EvictionPolicy) Interface

type LFU

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

func NewLFU

func NewLFU(size int) *LFU

func (*LFU) Evict

func (c *LFU) Evict(keys ...interface{}) int

func (*LFU) Flush

func (c *LFU) Flush()

func (*LFU) Get

func (c *LFU) Get(x interface{}) (y interface{}, exp *time.Time, err error)

func (*LFU) Metrics

func (c *LFU) Metrics() Metrics

func (*LFU) Set

func (c *LFU) Set(x, y interface{}, exp *time.Time) (err error)

func (*LFU) Trim

func (c *LFU) Trim(now time.Time) []interface{}

type LRU

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

func NewLRU

func NewLRU(size int) *LRU

func (*LRU) Evict

func (c *LRU) Evict(keys ...interface{}) int

func (*LRU) Flush

func (c *LRU) Flush()

func (*LRU) Get

func (c *LRU) Get(x interface{}) (y interface{}, exp *time.Time, err error)

func (*LRU) Metrics

func (c *LRU) Metrics() Metrics

func (*LRU) Set

func (c *LRU) Set(x, y interface{}, exp *time.Time) (err error)

func (*LRU) Trim

func (c *LRU) Trim(now time.Time) []interface{}

type Metrics

type Metrics struct {
	Hit, Miss, Evict, Expired, Items int64
}

type Upstream

type Upstream interface {
	Get(x interface{}) (y interface{}, exp *time.Time, err error)
}

func Blocking

func Blocking(up Upstream) Upstream

Blocking avoids multiple simultaneous requests for the same key

func Proxy

func Proxy(u Upstream, c Interface) Upstream

type UpstreamFunc

type UpstreamFunc func(x interface{}) (y interface{}, exp *time.Time, err error)

func (UpstreamFunc) Get

func (f UpstreamFunc) Get(x interface{}) (y interface{}, exp *time.Time, err error)