lcw

README

Loading Cache Wrapper

The library adds a thin layer on top of lru cache and patrickmn/go-cache.

Cache name	Constructor	Defaults	Description
LruCache	lcw.NewLruCache	keys=1000	LRU cache with limits
ExpirableCache	lcw.NewExpirableCache	keys=1000, ttl=5m	TTL cache with limits
Nop	lcw.NewNopCache		Do-nothing cache

Main features:

• LoadingCache (guava style)
• Limit maximum cache size (in bytes)
• Limit maximum key size
• Limit maximum size of a value
• Limit number of keys
• TTL support (ExpirableCache only)
• Callback on eviction event
• Functional style invalidation
• Functional options
• Sane defaults

Install and update

go get -u github.com/go-pkgz/lcw

Usage

cache := lcw.NewLruCache(lcw.MaxKeys(500), lcw.MaxCacheSize(65536), lcw.MaxValSize(200), lcw.MaxKeySize(32))

val, err := cache.Get("key123", func() (lcw.Value, error) {
    res, err := getDataFromSomeSource(params) // returns string
    return res, err
})

if err != nil {
    panic("failed to get data")
}

s := val.(string) // cached value

Details

• All byte-size limits (MaxCacheSize and MaxValSize) only work for values implementing lcw.Sizer interface.
• Negative limits (max options) rejected
• lgr.Value wraps interface{} and should be converted back to the concrete type.
• The implementation started as a part of remark42 and later on moved to go-pkgz/rest library and finaly generalized to become lcw.

Documentation

Overview

Package lcw adds a thin layer on top of lru cache and go-cache providing more limits and common interface. The primary method to get (and set) data to/from the cache is LoadingCache.Get retruning stored data for a given key or call provided func to retrive and store, similar to Guava loading cache. Limits allow max values for key size, number of keys, value size and total size of values in the cache. CacheStat gives general stats on cache performance. 3 flavours of cache provided - NoP (do-nothing cache), ExpirableCache (TTL based), and LruCache

Index

• type CacheStat
  • func (s *CacheStat) String() string
• type ExpirableCache
  • func NewExpirableCache(opts ...Option) (*ExpirableCache, error)
  • func (c *ExpirableCache) Delete(key string)
  • func (c *ExpirableCache) Get(key string, fn func() (Value, error)) (data Value, err error)
  • func (c *ExpirableCache) Invalidate(fn func(key string) bool)
  • func (c *ExpirableCache) Peek(key string) (Value, bool)
  • func (c *ExpirableCache) Purge()
  • func (c *ExpirableCache) Stat() CacheStat
• type LoadingCache
• type LruCache
  • func NewLruCache(opts ...Option) (*LruCache, error)
  • func (c *LruCache) Delete(key string)
  • func (c *LruCache) Get(key string, fn func() (Value, error)) (data Value, err error)
  • func (c *LruCache) Invalidate(fn func(key string) bool)
  • func (c *LruCache) Peek(key string) (Value, bool)
  • func (c *LruCache) Purge()
  • func (c *LruCache) Stat() CacheStat
• type Nop
  • func NewNopCache() *Nop
  • func (n *Nop) Delete(key string)
  • func (n *Nop) Get(key string, fn func() (Value, error)) (Value, error)
  • func (n *Nop) Invalidate(fn func(key string) bool)
  • func (n *Nop) Peek(key string) (Value, bool)
  • func (n *Nop) Purge()
  • func (n *Nop) Stat() CacheStat
• type Option
  • func MaxCacheSize(max int64) Option
  • func MaxKeySize(max int) Option
  • func MaxKeys(max int) Option
  • func MaxValSize(max int) Option
  • func OnEvicted(fn func(key string, value Value)) Option
  • func TTL(ttl time.Duration) Option
• type Sizer
• type Value

Examples

• LruCache

Types

type CacheStat

type CacheStat struct {
	Hits   int64
	Misses int64
	Keys   int
	Size   int64
	Errors int64
}

CacheStat represent stats values

func (*CacheStat) String

func (s *CacheStat) String() string

String formats cache stats

type ExpirableCache

type ExpirableCache struct {
	CacheStat
	// contains filtered or unexported fields
}

ExpirableCache implements LoadingCache with TTL.

func NewExpirableCache

func NewExpirableCache(opts ...Option) (*ExpirableCache, error)

NewExpirableCache makes expirable LoadingCache implementation, 1000 max keys by default and 5s TTL

func (*ExpirableCache) Delete

func (c *ExpirableCache) Delete(key string)

Delete cache item by key

func (*ExpirableCache) Get

func (c *ExpirableCache) Get(key string, fn func() (Value, error)) (data Value, err error)

Get gets value by key or load with fn if not found in cache

func (*ExpirableCache) Invalidate

func (c *ExpirableCache) Invalidate(fn func(key string) bool)

Invalidate removes keys with passed predicate fn, i.e. fn(key) should be true to get evicted

func (*ExpirableCache) Peek

func (c *ExpirableCache) Peek(key string) (Value, bool)

Peek returns the key value (or undefined if not found) without updating the "recently used"-ness of the key.

func (*ExpirableCache) Purge

func (c *ExpirableCache) Purge()

Purge clears the cache completely.

func (*ExpirableCache) Stat

func (c *ExpirableCache) Stat() CacheStat

Stat returns cache statistics

type LoadingCache

type LoadingCache interface {
	Get(key string, fn func() (Value, error)) (val Value, err error) // load or get from cache
	Peek(key string) (Value, bool)                                   // get from cache by key
	Invalidate(fn func(key string) bool)                             // invalidate items for func(key) == true
	Delete(key string)                                               // delete by key
	Purge()                                                          // clear cache
	Stat() CacheStat                                                 // cache stats
}

LoadingCache defines guava-like cache with Get method returning cached value ao retrieving it if not in cache

type LruCache

type LruCache struct {
	CacheStat
	// contains filtered or unexported fields
}

LruCache wraps lru.LruCache with laoding cache Get and size limits

Example

LruCache illustrates the use of LRU loading cache

// load page function
loadURL := func(url string) (string, error) {
	resp, err := http.Get(url)
	if err != nil {
		return "", err
	}
	_ = resp.Body.Close()
	b, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		return "", err
	}
	return string(b), nil
}

// fixed size LRU cache, 100 items, up to 10k in total size
cache, err := NewLruCache(MaxKeys(100), MaxCacheSize(10*1024))
if err != nil {
	log.Fatalf("can't make lru cache, %v", err)
}

// url not in cache, load data
url := "https://radio-t.com/online/"
val, err := cache.Get(url, func() (val Value, err error) {
	return loadURL(url)
})
if err != nil {
	log.Fatalf("can't load url %s, %v", url, err)
}
log.Print(val.(string))

// url not in cache, load data
url = "https://radio-t.com/info/"
val, err = cache.Get(url, func() (val Value, err error) {
	return loadURL(url)
})
if err != nil {
	log.Fatalf("can't load url %s, %v", url, err)
}
log.Print(val.(string))

// url cached, skip load and get from the cache
url = "https://radio-t.com/online/"
val, err = cache.Get(url, func() (val Value, err error) {
	return loadURL(url)
})
if err != nil {
	log.Fatalf("can't load url %s, %v", url, err)
}
log.Print(val.(string))

func NewLruCache

func NewLruCache(opts ...Option) (*LruCache, error)

NewLruCache makes LRU LoadingCache implementation, 1000 max keys by default

func (*LruCache) Delete

func (c *LruCache) Delete(key string)

Delete cache item by key

func (*LruCache) Get

func (c *LruCache) Get(key string, fn func() (Value, error)) (data Value, err error)

Get gets value by key or load with fn if not found in cache

func (*LruCache) Invalidate

func (c *LruCache) Invalidate(fn func(key string) bool)

Invalidate removes keys with passed predicate fn, i.e. fn(key) should be true to get evicted

func (*LruCache) Peek

func (c *LruCache) Peek(key string) (Value, bool)

Peek returns the key value (or undefined if not found) without updating the "recently used"-ness of the key.

func (*LruCache) Purge

func (c *LruCache) Purge()

Purge clears the cache completely.

func (*LruCache) Stat

func (c *LruCache) Stat() CacheStat

Stat returns cache statistics

type Nop

type Nop struct{}

Nop is do-nothing implementation of LoadingCache

func NewNopCache

func NewNopCache() *Nop

NewNopCache makes new do-nothing cache

func (*Nop) Delete

func (n *Nop) Delete(key string)

Delete does nothing for nop cache

func (*Nop) Get

func (n *Nop) Get(key string, fn func() (Value, error)) (Value, error)

Get calls fn without any caching

func (*Nop) Invalidate

func (n *Nop) Invalidate(fn func(key string) bool)

Invalidate does nothing for nop cache

func (*Nop) Peek

func (n *Nop) Peek(key string) (Value, bool)

Peek does nothing and always returns false

func (*Nop) Purge

func (n *Nop) Purge()

Purge does nothing for nop cache

func (*Nop) Stat

func (n *Nop) Stat() CacheStat

Stat always 0s for nop cache

type Option

type Option func(o *options) error

Option func type

func MaxCacheSize

func MaxCacheSize(max int64) Option

MaxCacheSize functional option defines the total size of cached data. By default it is 0, which means unlimited.

func MaxKeySize

func MaxKeySize(max int) Option

MaxKeySize functional option defines the largest key's size allowed to be used in cache By default it is 0, which means unlimited.

func MaxKeys

func MaxKeys(max int) Option

MaxKeys functional option defines how many keys to keep. By default it is 0, which means unlimited.

func MaxValSize

func MaxValSize(max int) Option

MaxValSize functional option defines the largest value's size allowed to be cached By default it is 0, which means unlimited.

func OnEvicted

func OnEvicted(fn func(key string, value Value)) Option

OnEvicted sets callback on invalidation event

func TTL

func TTL(ttl time.Duration) Option

TTL functional option defines duration. Works for ExpirableCache only

type Sizer

type Sizer interface {
	Size() int
}

Sizer allows to perform size-based restrictions, optional. If not defined both maxValueSize and maxCacheSize checks will be ignored

type Value

type Value interface{}

Value type wraps interface{}