memcache

Documentation

Index

• Variables
• func AddRawFilters(c context.Context, filts ...RawFilter) context.Context
• func SetRaw(c context.Context, mc RawInterface) context.Context
• func SetRawFactory(c context.Context, mcf RawFactory) context.Context
• type Interface
  • func Get(c context.Context) Interface
• type Item
• type RawCB
• type RawFactory
• type RawFilter
• type RawInterface
  • func GetRaw(c context.Context) RawInterface
• type RawItemCB
• type Statistics

Variables

var (
	ErrCacheMiss   = orig.ErrCacheMiss
	ErrCASConflict = orig.ErrCASConflict
	ErrNoStats     = orig.ErrNoStats
	ErrNotStored   = orig.ErrNotStored
	ErrServerError = orig.ErrServerError
)

These are pass-through versions from the managed-VM SDK. All implementations must return these (exact) errors (not just an error with the same text).

Functions

func AddRawFilters

func AddRawFilters(c context.Context, filts ...RawFilter) context.Context

AddRawFilters adds RawInterface filters to the context.

func SetRaw

func SetRaw(c context.Context, mc RawInterface) context.Context

SetRaw sets the current RawInterface object in the context. Useful for testing with a quick mock. This is just a shorthand SetRawFactory invocation to SetRaw a RawFactory which always returns the same object.

func SetRawFactory

func SetRawFactory(c context.Context, mcf RawFactory) context.Context

SetRawFactory sets the function to produce RawInterface instances, as returned by the Get method.

Types

type Interface

type Interface interface {
	// NewItem creates a new, mutable, memcache item.
	NewItem(key string) Item

	// Add puts a single item into memcache, but only if it didn't exist in
	// memcache before.
	Add(item Item) error

	// Set the item in memcache, whether or not it exists.
	Set(item Item) error

	// Get retrieves an item from memcache.
	//
	// On a cache miss ErrCacheMiss will be returned. Item will always be
	// returned, even on a miss, but it's value may be empty if it was a miss.
	Get(key string) (Item, error)

	// Delete removes an item from memcache.
	Delete(key string) error

	// CompareAndSwap accepts an item which is the result of Get() or GetMulti().
	// The Get functions add a secret field to item ('CasID'), which is used as
	// the "compare" value for the "CompareAndSwap". The actual "Value" field of
	// the object set by the Get functions is the "swap" value.
	//
	// Example:
	//   mc := memcache.Get(context)
	//   itm := mc.NewItem("aKey")
	//   mc.Get(itm) // check error
	//   itm.SetValue(append(itm.Value(), []byte("more bytes")))
	//   mc.CompareAndSwap(itm) // check error
	CompareAndSwap(item Item) error

	// Batch operations; GetMulti takes a []Item instead of []string to improve
	// ergonomics when streamlining these operations.
	AddMulti(items []Item) error
	SetMulti(items []Item) error
	GetMulti(items []Item) error
	DeleteMulti(keys []string) error
	CompareAndSwapMulti(items []Item) error

	// Increment adds delta to the uint64 contained at key. If the memcache key
	// is missing, it's populated with initialValue before applying delta (i.e.
	// the final value would be initialValue+delta).
	//
	// Underflow caps at 0, overflow wraps back to 0.
	//
	// If key contains a value which is not exactly 8 bytes, it's assumed to
	// contain non-number data and this method will return an error.
	Increment(key string, delta int64, initialValue uint64) (newValue uint64, err error)

	// IncrementExisting is like Increment, except that the valu must exist
	// already.
	IncrementExisting(key string, delta int64) (newValue uint64, err error)

	// Flush dumps the entire memcache state.
	Flush() error

	// Stats gets some best-effort statistics about the current state of memcache.
	Stats() (*Statistics, error)

	Raw() RawInterface
}

Interface is the full interface to the memcache service.

The *Multi methods may return a "github.com/luci/luci-go/common/errors".MultiError if the rpc to the server was successful, but, e.g. some of the items were missing. They may also return a regular error, if, for example, the rpc failed outright.

func Get

func Get(c context.Context) Interface

Get gets the current memcache implementation from the context.

type Item

type Item interface {
	Key() string
	Value() []byte
	Flags() uint32
	Expiration() time.Duration

	SetKey(string) Item
	SetValue([]byte) Item
	SetFlags(uint32) Item
	SetExpiration(time.Duration) Item

	// SetAll copies all the values from other, except Key, into this item
	// (including the hidden CasID field). If other is nil, then all non-Key
	// fields are reset.
	SetAll(other Item)
}

Item is a wrapper around *memcache.Item. Note that the Set* methods all return the original Item (e.g. they mutate the original), due to implementation constraints. They return the original item to allow easy chaining, e.g.:

itm := memcache.Get(c).NewItem("foo").SetValue([]byte("stuff"))

type RawCB

type RawCB func(error)

RawCB is a simple error callback for most of the methods in RawInterface.

type RawFactory

type RawFactory func(context.Context) RawInterface

RawFactory is the function signature for RawFactory methods compatible with SetRawFactory.

type RawFilter

type RawFilter func(context.Context, RawInterface) RawInterface

RawFilter is the function signature for a RawFilter MC implementation. It gets the current MC implementation, and returns a new MC implementation backed by the one passed in.

type RawInterface

type RawInterface interface {
	NewItem(key string) Item

	AddMulti(items []Item, cb RawCB) error
	SetMulti(items []Item, cb RawCB) error
	GetMulti(keys []string, cb RawItemCB) error
	DeleteMulti(keys []string, cb RawCB) error
	CompareAndSwapMulti(items []Item, cb RawCB) error

	Increment(key string, delta int64, initialValue *uint64) (newValue uint64, err error)

	Flush() error

	Stats() (*Statistics, error)
}

RawInterface is the full interface to the memcache service.

func GetRaw

func GetRaw(c context.Context) RawInterface

GetRaw gets the current memcache implementation from the context.

type RawItemCB

type RawItemCB func(Item, error)

RawItemCB is the callback for RawInterface.GetMulti. It takes the retrieved item and the error for that item (e.g. ErrCacheMiss) if there was one. Item is guaranteed to be nil if error is not nil.

type Statistics

type Statistics struct {
	Hits     uint64 // Counter of cache hits
	Misses   uint64 // Counter of cache misses
	ByteHits uint64 // Counter of bytes transferred for gets

	Items uint64 // Items currently in the cache
	Bytes uint64 // Size of all items currently in the cache

	Oldest int64 // Age of access of the oldest item, in seconds
}

Statistics represents a set of statistics about the memcache cache. This may include items that have expired but have not yet been removed from the cache.