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 ¶
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.
Variables ¶
This section is empty.
Functions ¶
func Decode ¶
Decode is a convenience method for decoding a ZLIB-compressed JSON-encoded object encoded by Encode.
func HashParams ¶
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 ¶
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.
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.
type Loader ¶
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 ¶
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 ¶
DecodeValue loads a Value from is encoded representation.
func (*Value) ConfigItems ¶
ConfigItems returns the config.Config projection of v's Items slice.
func (*Value) Description ¶
Description returns a human-readable string describing the contents of this value.
func (*Value) Encode ¶
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 ¶
LoadItems loads a set of config.Config into v's Items field. If items is nil, v.Items will be nil.
func (*Value) SingleItem ¶
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 ¶
MakeValueItem builds a caching ValueItem from a config.Config.
func (*ValueItem) ConfigItem ¶
ConfigItem returns the config.Config equivalent of vi.
Source Files