caching

Documentation

Overview

Package caching implements a config.Interface that uses a caching layer to store its configuration values.

The Backend in this package is generic, and does not implement that actual caching interface. Instead, the user should pair it with a cache implementation by implementing its CacheGet method.

Some example caches include:

• Process in-memory cache.
• memcache, or AppEngine's memcache service.
• A local storage cache (e.g., on-disk)
• A datastore cache.

Index

• Constants
• func Decode(d []byte, v interface{}) error
• func Encode(v interface{}) ([]byte, error)
• func HashParams(params ...string) []byte
• func LRUBackend(b backend.B, cache *lru.Cache, exp time.Duration) backend.B
• type Backend
  • func (b *Backend) Get(c context.Context, configSet config.Set, path string, p backend.Params) (*config.Config, error)
  • func (b *Backend) GetAll(c context.Context, t backend.GetAllTarget, path string, p backend.Params) ([]*config.Config, error)
• type Key
  • func (k *Key) ParamHash() []byte
  • func (k *Key) Params() backend.Params
  • func (k *Key) String() string
• type Loader
• type Operation
• type Value
  • func CacheLoad(c context.Context, b backend.B, k Key, v *Value) (rv *Value, err error)
  • func DecodeValue(d []byte) (*Value, error)
  • func (v *Value) ConfigItems() []*config.Config
  • func (v *Value) Description() string
  • func (v *Value) Encode() ([]byte, error)
  • func (v *Value) LoadItems(items ...*config.Config)
  • func (v *Value) SingleItem() *config.Config
• type ValueItem
  • func MakeValueItem(it *config.Config) ValueItem
  • func (vi *ValueItem) ConfigItem() *config.Config

Constants

const (
	// OpGet is the Get operation.
	OpGet = Operation("Get")
	// OpGetAll is the GetAll operation.
	OpGetAll = Operation("GetAll")
)

const Schema = "v2"

Schema is the current package's cache schema.

Functions

func Decode

func Decode(d []byte, v interface{}) error

Decode is a convenience method for decoding a ZLIB-compressed JSON-encoded object encoded by Encode.

func Encode

func Encode(v interface{}) ([]byte, error)

Encode is a convenience method for generating a ZLIB-compressed JSON-encoded object.

func HashParams

func HashParams(params ...string) []byte

HashParams is a convenience method for hashing a series of strings into a unique hash key for that series.

The output is fixed-size sha256.Size (32) bytes.

func LRUBackend

func LRUBackend(b backend.B, cache *lru.Cache, exp time.Duration) backend.B

LRUBackend wraps b, applying the additional cache to its results.

Do NOT chain multiple LRUBackend in the same backend chain. An LRUBackend holds a LRU-wide lock on its cache key when it looks up its value, and if a second entity attempts to lock that same key during its lookup chain, the lookup will deadlock.

If the supplied expiration is <= 0, no additional caching will be performed.

Types

type Backend

type Backend struct {
	// Backend is the backing Backend.
	backend.B

	// FailOnError, if true, means that a failure to retrieve a cached item will
	// be propagated to the caller immediately. If false, a cache error will
	// result in a direct fall-through call to the embedded backend.B.
	//
	// One might set FailOnError to true if the fallback is unacceptably slow, or
	// if they want to enforce caching via failure.
	FailOnError bool

	// CacheGet retrieves the cached value associated with key. If no such cached
	// value exists, CacheGet is responsible for resolving the cache value using
	// the supplied Loader.
	CacheGet func(context.Context, Key, Loader) (*Value, error)
}

Backend is a backend.B implementation that caches responses.

All cached values are full-content regardless of whether or not full content was requested.

Backend caches content and no-content requests as separate cache entries. This enables one cache to do low-overhead updating against another cache implementation.

func (*Backend) Get

func (b *Backend) Get(c context.Context, configSet config.Set, path string, p backend.Params) (*config.Config, error)

Get implements backend.B.

func (*Backend) GetAll

func (b *Backend) GetAll(c context.Context, t backend.GetAllTarget, path string, p backend.Params) ([]*config.Config, error)

GetAll implements config.Backend.

type Key

type Key struct {
	// Schema is the schema for this key/value. If schema changes in a backwards-
	// incompatible way, this must also change.
	Schema string `json:"s,omitempty"`

	// ServiceURL is the URL of the config service.
	ServiceURL string `json:"u,omitempty"`

	// Authority is the config authority to use.
	Authority backend.Authority `json:"a,omitempty"`

	// Op is the operation that is being cached.
	Op Operation `json:"op,omitempty"`

	// Content is true if this request asked for content.
	Content bool `json:"c,omitempty"`

	// Formatter is the requesting Key's Formatter parameter, expanded from its
	// FormatSpec.
	Formatter string `json:"f,omitempty"`
	// FormatData is the requesting Key's format Data parameter, expanded from its
	// FormatSpec.
	FormatData string `json:"fd,omitempty"`

	// ConfigSet is the config set parameter. This is valid for "OpGet".
	ConfigSet config.Set `json:"cs,omitempty"`
	// Path is the path parameters. This is valid for "OpGet" and "OpGetAll".
	Path string `json:"p,omitempty"`

	// GetAllTarget is the "GetAll" operation type. This is valid for "OpGetAll".
	GetAllTarget backend.GetAllTarget `json:"gat,omitempty"`
}

Key is a cache key.

func (*Key) ParamHash

func (k *Key) ParamHash() []byte

ParamHash returns a deterministic hash of all of the key parameters.

func (*Key) Params

func (k *Key) Params() backend.Params

Params returns the backend.Params that are encoded in this Key.

func (*Key) String

func (k *Key) String() string

String prints a text representation of the key. No effort is made to ensure that this representation is consistent or deterministic, and it is not bound to the cache schema.

type Loader

type Loader func(context.Context, Key, *Value) (*Value, error)

Loader retrieves a Value by consulting the backing backend.

The input Value is the current cached Value, or nil if there is no current cached Value. The output Value is the cached Value, if one exists. It is acceptable to return mutate "v" and/or return it as the output Value.

type Operation

type Operation string

Operation is a cache entry operation. Cache entries are all stored in the same object, with different parameters filled based on the operation that they represent.

type Value

type Value struct {
	// Items is the cached set of config response items.
	//
	// For Get, this will either be empty (cached miss) or have a single Item
	// in it (cache hit).
	Items []ValueItem `json:"i,omitempty"`
}

Value is a cache value.

func CacheLoad

func CacheLoad(c context.Context, b backend.B, k Key, v *Value) (rv *Value, err error)

CacheLoad loads k from backend b.

If an existing cache value is known, it should be supplied as v. Otherwise, v should be nil.

This is effectively a Loader function that is detached from a given cache instance.

func DecodeValue

func DecodeValue(d []byte) (*Value, error)

DecodeValue loads a Value from is encoded representation.

func (*Value) ConfigItems

func (v *Value) ConfigItems() []*config.Config

ConfigItems returns the config.Config projection of v's Items slice.

func (*Value) Description

func (v *Value) Description() string

Description returns a human-readable string describing the contents of this value.

func (*Value) Encode

func (v *Value) Encode() ([]byte, error)

Encode encodes this Value.

This is offered for convenience, but caches aren't required to use this encoding.

The format stores the Value as compressed JSON.

func (*Value) LoadItems

func (v *Value) LoadItems(items ...*config.Config)

LoadItems loads a set of config.Config into v's Items field. If items is nil, v.Items will be nil.

func (*Value) SingleItem

func (v *Value) SingleItem() *config.Config

SingleItem returns the first config.Config in v's Items slice. If the Items slice is empty, SingleItem will return nil.

type ValueItem

type ValueItem struct {
	ConfigSet string `json:"cs,omitempty"`
	Path      string `json:"p,omitempty"`

	ContentHash string `json:"ch,omitempty"`
	Revision    string `json:"r,omitempty"`
	ViewURL     string `json:"v,omitempty"`

	Content []byte `json:"c,omitempty"`

	Formatter  string `json:"f,omitempty"`
	FormatData []byte `json:"fd,omitempty"`
}

ValueItem is a cache-optimized config.Config projection.

This will mostly be the same as a config.Config, with the exception of Content, which will hold the formatted value if it has been formatted.

See Formatter in go.chromium.org/luci/config/server/cfgclient and Backend in go.chromium.org/luci/config/server/cfgclient.backend/format for more information.

func MakeValueItem

func MakeValueItem(it *config.Config) ValueItem

MakeValueItem builds a caching ValueItem from a config.Config.

func (*ValueItem) ConfigItem

func (vi *ValueItem) ConfigItem() *config.Config

ConfigItem returns the config.Config equivalent of vi.