cache

Documentation

Overview

Package cache implements a caching system with pluggable backends.

The cache is configured with a gnd.la/config.URL, which takes the form:

scheme://value?var=value&var2=value#anothervar=anothervalue

While each driver might implement its own options, there are 3 options which apply to all drivers and are specified after the # character. They are:

• codec: The codec used for encoding/decoding the cached objects. See gnd.la/encoding/codec for the available ones.
• pipe: A pipe to pass the data trough, usually for compressing it. See gnd.la/encoding/pipe for the available ones.
• prefix: A prefix to be prepended to all keys stored.

Note that these options are not mandatory. For the available drivers, see gnd.la/cache/driver for the ones without dependencies and its subpackages for the ones with external dependencies.

Some examples of valid configurations:

memcache://localhost#codec=json&pipe=zlib
memory://#max_size=1.5G
file://cache#max_size=512M

Index

• Variables
• type Cache
  • func New(url *config.URL) (*Cache, error)
  • func (c *Cache) Close() error
  • func (c *Cache) Connection() interface{}
  • func (c *Cache) Delete(key string) error
  • func (c *Cache) Flush() error
  • func (c *Cache) Get(key string, obj interface{}) error
  • func (c *Cache) GetBytes(key string) ([]byte, error)
  • func (c *Cache) GetMulti(out map[string]interface{}, typer Typer) error
  • func (c *Cache) Set(key string, object interface{}, timeout int) error
  • func (c *Cache) SetBytes(key string, b []byte, timeout int) error
• type Typer
  • func UniTyper(obj interface{}) Typer

Variables

var (
	ErrNotFound = errors.New("item not found in cache")
)

Types

type Cache

type Cache struct {
	// The Logger to log debug messages and, more importantly, errors.
	// New() initialies the log.Logger to log.Std.
	Logger *log.Logger
	// contains filtered or unexported fields
}

func New

func New(url *config.URL) (*Cache, error)

New returns a new cache instance, using the given configuration URL. If the configuration is nil, a dummy cache is returned, which always returns that the object does not exists in the cache.

func (*Cache) Close

func (c *Cache) Close() error

Close closes the cache connection. If you're using a cache using app.Context helper methods, the cache will be closed for you.

func (*Cache) Connection

func (c *Cache) Connection() interface{}

Connection returns a interface{} wrapping the native connection type for the cache client (e.g. a memcache or redis connection). Some drivers might return a nil connection (like the fs or the dummy driver).

func (*Cache) Delete

func (c *Cache) Delete(key string) error

Delete removes the key from the cache. An error is returned only if the item was found but couldn't be deleted. Deleting a non-existant item is always successful.

func (*Cache) Flush

func (c *Cache) Flush() error

Flush removes all items from the cache.

func (*Cache) Get

func (c *Cache) Get(key string, obj interface{}) error

Get retrieves the requested item from the cache and decodes it into the passed interface{}, which must be addressable. If the item is not found in the cache, ErrNotFound is returned. Other errors mean that either there was a problem communicating with the cache or the item could not be decoded.

func (*Cache) GetBytes

func (c *Cache) GetBytes(key string) ([]byte, error)

GetBytes returns the byte array assocciated with the given key

func (*Cache) GetMulti

func (c *Cache) GetMulti(out map[string]interface{}, typer Typer) error

GetMulti returns several objects with only one trip to the cache. The queried keys are the ones set in the out parameter. Any key present in out and not found when querying the cache, will be deleted. The initial values in the out map should be any value of the type which will be used to decode the data for the given key. e.g. Let's suppose our cache holds 3 objects: k1 of type []int, k2 of type float64 and k3 of type string. To query for these 3 objects using GetMulti you would initialze out like this:

 out := map[string]interface{}{
	k1: []int(nil),
	k2: float(0),
	k3: "",
 }
 err := c.GetMulti(out, nil)

After the GetMulti() call, any keys not present in the cache will be deleted from out, so len(out) will be <= 3 in this example.

Alternatively, the second argument might be used to specify the types of the object to be decoded. Users might implement their own Typer or use UniTyper when requesting several objects of the same type.

func (*Cache) Set

func (c *Cache) Set(key string, object interface{}, timeout int) error

Set stores the given object in the cache associated with the given key. Timeout is the number of seconds until the item expires. If the timeout is 0, the item never expires, but might be only purged from cache when running out of space.

func (*Cache) SetBytes

func (c *Cache) SetBytes(key string, b []byte, timeout int) error

SetBytes stores the given byte array assocciated with the given key. See the documentation for Set for an explanation of the timeout parameter

type Typer

type Typer interface {
	Type(key string) reflect.Type
}

Typer returns the type of object to be decoded for a given key.

func UniTyper

func UniTyper(obj interface{}) Typer

UniType returns a Typer which returns the type of obj for all the keys.