cache

README

Golang local cache

Implementation of simple local cache.

Features & todos:

• prevents "dogpile effect"
• check data expiration time
• lru policy
• cache hit and enviction stats

Cache limitations:

• keys are always int
• get function returns multiple values
• set function sets multiple keys at once
• to prevent dog pile effect queueKey should be manually set

How to use

Create cache instance

import "github.com/sima-land/go-local-cache"
c := cache.New()

Create getter function. Its preferred way to fill the cache because in case of "dog pile" effect getter will be called once.

getter := func(keys Keys) (Result, error) {
	r := Result{}
	for _, k := range keys {
		// haavy call to database
		r[k] = db.GetByID(k)		
	}
	return r, nil
}

Obtain data from cache. If there is no data in the cache getter will be called.

Note:

1. Next call is concurrently safe
2. If too many go-routines in our application are trying to call this getter with same queue key (user-1) then only first call will actually be done

result, err := c.Get(int[]{1}, getter, "user-1")

QueueKey param explain

You can simple use entity name and id as queueKey param of Get function. Eg:

result, err := c.Get(int[]{1}, userGetter, "user-1")
result, err := c.Get(int[]{1}, productGetter, "product-1")

Or if you need to get a page of product's block whole page. If keys 1,2 are in cache but other keys are not then:

1. Keys 1 and 2 will be get from cache
2. Getter will be called for keys 3,4,5 and 6
3. If another getter with same queue key "product-1" was called before and first one will be used instead

result, err := c.Get(int[]{1,2,3,4,5,6}, userGetter, "product-page-1")

Options

Cache has a variety of configuration options:

c := cache.New(cache.Options{
		MaxEntries: 1000000, // Specify max number items in cache
		TTL: time.Hour, // Time to live for cache entries
	})

Test

MacBook 2,7 GHz Intel Core i5

BenchmarkCache_Get-4      500000              2274 ns/op
BenchmarkCache_Get-4      500000              2335 ns/op

Documentation

Index

• type Cache
  • func New(options ...Options) *Cache
  • func (c *Cache) Flush(n int)
  • func (c *Cache) Get(keys Keys, getter Getter, queueKey interface{}) (Result, error)
  • func (c *Cache) Len() int
  • func (c *Cache) Remove(keys Keys)
  • func (c *Cache) Set(data Result)
• type Getter
• type Keys
• type Options
• type Queue
  • func NewQueue() *Queue
  • func (q *Queue) Do(keys Keys, getter Getter, queueKey interface{}) (Result, error)
• type Result

Types

type Cache

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

Cache represents cache

func New

func New(options ...Options) *Cache

New initializes new instance of cache

func (*Cache) Flush

func (c *Cache) Flush(n int)

Flush removes last (rare used) n elements from cache

func (*Cache) Get

func (c *Cache) Get(keys Keys, getter Getter, queueKey interface{}) (Result, error)

Get returns data from cache by keys

If data not exist Getter function will be called to get data Data returned by Getter function will be placed into cache

func (*Cache) Len

func (c *Cache) Len() int

Len returns the number of items in the cache

func (*Cache) Remove

func (c *Cache) Remove(keys Keys)

Remove removes the provided keys from the cache.

func (*Cache) Set

func (c *Cache) Set(data Result)

Set saves result into cache

type Getter

type Getter func(keys Keys) (Result, error)

Getter func must be implemented by client and returns data by it's keys

type Keys

type Keys []int

Keys represents set of cache keys It always slice of int for two reasons: - we do not have separate Get and GetMulti functions - integers are most common used primary keys in db

type Options

type Options struct {
	MaxEntries int
	TTL        time.Duration
}

Options keeps cache options

type Queue

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

Queue of calls. Provides a duplicate function call suppression mechanism. Based on google group cache singleflight package.

func NewQueue

func NewQueue() *Queue

NewQueue initialize new Queue

func (*Queue) Do

func (q *Queue) Do(keys Keys, getter Getter, queueKey interface{}) (Result, error)

Do place call in queue of calls with same queueKey and returns results of first call in queue

type Result

type Result map[int]interface{}

Result represents result returned by cache function