proccache

Documentation

Overview

Package proccache implements a simple in-memory cache that can be injected into a context and shared by all request handlers executing within a process. Same can be achieved by using global variables, but global state complicates unit testing.

Example

counter := 0
slowCall := func(c context.Context) (int, error) {
	counter++
	return counter, nil
}

cachedCall := Cached("key", func(c context.Context, key interface{}) (interface{}, time.Duration, error) {
	val, err := slowCall(c)
	return val, 0, err
})

// Default context silently skips caching.
ctx := context.Background()
a, _ := cachedCall(ctx)
b, _ := cachedCall(ctx)
fmt.Printf("%d, %d\n", a, b)

// Injecting *Cache in the context makes it "remember" cached values.
ctx = Use(context.Background(), &Cache{})
a, _ = cachedCall(ctx)
b, _ = cachedCall(ctx)
fmt.Printf("%d, %d\n", a, b)

Output:

1, 2
3, 3

Index

• func Add(c context.Context, key, value interface{}, exp time.Duration) (added bool, out interface{})
• func Get(c context.Context, key interface{}) (value interface{}, ok bool)
• func GetOrMake(c context.Context, key interface{}, maker Maker) (interface{}, error)
• func Put(c context.Context, key, value interface{}, exp time.Duration)
• func Use(c context.Context, cache *Cache) context.Context
• type Cache
  • func GetCache(c context.Context) *Cache
  • func (c *Cache) Get(key interface{}) *Entry
  • func (c *Cache) Mutate(key interface{}, callback func(*Entry) *Entry)
  • func (c *Cache) Put(key, value interface{}, exp time.Time)
• type Entry
• type Getter
  • func Cached(key interface{}, warmer Warmer) Getter
• type Maker
• type Warmer

Examples

• Package

Functions

func Add

func Add(c context.Context, key, value interface{}, exp time.Duration) (added bool, out interface{})

Add atomically adds an item to the cache if it's not currently cached or existing item has expired.

Returns (true, new item) if the item was added, (false, existing item) if the item existed before.

func Get

func Get(c context.Context, key interface{}) (value interface{}, ok bool)

Get returns an item from cache in the context if it hasn't expired yet. If there's no such item or it has expired, returns (nil, false).

func GetOrMake

func GetOrMake(c context.Context, key interface{}, maker Maker) (interface{}, error)

GetOrMake attempts to grab an item from the cache. If it's not there, it calls a supplied `maker` callback to generate it and uses Add to place it in the cache. If some concurrent operation managed to put an item in the cache in between the calls, existing item is returned and return value of `maker` is discarded. Returns error only if `maker` returns error.

func Put

func Put(c context.Context, key, value interface{}, exp time.Duration)

Put grabs an instance of Cache from the context and puts an item in it. Zero expiration duration means the item doesn't expire. If context doesn't have a cache installed, Put is noop.

func Use

func Use(c context.Context, cache *Cache) context.Context

Use injects instance of Cache in the context.

Types

type Cache

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

Cache holds a mapping key -> (value, expiration time). The mapping is never cleared automatically, store only O(1) number of items there.

func GetCache

func GetCache(c context.Context) *Cache

GetCache grabs instance of Cache stored in the context, or creates a new one if nothing is stored.

func (*Cache) Get

func (c *Cache) Get(key interface{}) *Entry

Get returns a stored item or nil if no such item.

func (*Cache) Mutate

func (c *Cache) Mutate(key interface{}, callback func(*Entry) *Entry)

Mutate reads an entry, passes it to the callback, and writes back whatever callback returns. All under the lock. If such entry doesn't exist, callback receives nil. If callback returns nil, entry is removed from the cache.

func (*Cache) Put

func (c *Cache) Put(key, value interface{}, exp time.Time)

Put adds a new item to the cache or replaces an existing one.

type Entry

type Entry struct {
	Value interface{}
	Exp   time.Time
}

Entry is returned by Get. It is a stored value along with its expiration time (that may have already passed). Zero expiration time means the item doesn't expire.

type Getter

type Getter func(c context.Context) (interface{}, error)

Getter is returned by Cached. See Cached for more details.

func Cached

func Cached(key interface{}, warmer Warmer) Getter

Cached returns a getter function that extracts an item from the cache (if it is there) or calls a supplied callback to initialize and put it there. Intended to be used like a decorator for top level functions. The getter returns a error only if cache initialization callback (Warmer) returns a error. Warmer callback is not protected by any locks, and it may be called concurrently (and the cache will have the result of invocation that finished first, whatever it may be). Implement synchronization inside the callback itself if needed.

type Maker

type Maker func() (interface{}, time.Duration, error)

Maker is used by GetOrMake to make new cache item if previous one has expired. It returns a value to put in the cache along with its expiration duration (or 0 if it doesn't expire).

type Warmer

type Warmer func(c context.Context, key interface{}) (interface{}, time.Duration, error)

Warmer is used by Cached to make a new cache item if previous one has expired. It returns a value to put in the cache along with its expiration duration (or 0 if it doesn't expire). Unlike Maker, it doesn't expect the context and the key to be in the function closure and accepts them explicitly.