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
- type Entry
- type Getter
- type Maker
- type Warmer
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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 ¶
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 ¶
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 ¶
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.
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 ¶
GetCache grabs instance of Cache stored in the context, or creates a new one if nothing is stored.
func (*Cache) Get ¶
Get returns a stored item or nil if no such item.
func (*Cache) Mutate ¶
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.
type Entry ¶
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 ¶
Getter is returned by Cached. See Cached for more details.
func Cached ¶
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 ¶
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 ¶
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.
Source Files