luxolus/open-consul
2
0
Fork 0
Code Issues 1 Pull requests Packages Releases Wiki Activity

agent/cache: lots of comment/doc updates

Browse source
This commit is contained in:
Mitchell Hashimoto 2018-04-17 18:42:49 -05:00
parent a1f8cb9570
commit e9d58ca219
No known key found for this signature in database
GPG key ID: 744E147AA52F5B0A
2 changed files with 28 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

27
agent/cache/cache.go vendored
View file

@ -7,9 +7,11 @@
// balance performance and correctness, depending on the type of data being
// requested.
//
// Currently, the cache package supports only continuous, blocking query
// caching. This means that the cache update is edge-triggered by Consul
// server blocking queries.
// The types of data that can be cached is configurable via the Type interface.
// This allows specialized behavior for certain types of data. Each type of
// Consul data (CA roots, leaf certs, intentions, KV, catalog, etc.) will
// have to be manually implemented. This usually is not much work, see
// the "agent/cache-types" package.
package cache
import (
@ -23,7 +25,24 @@ import (
//go:generate mockery -all -inpkg
// Cache is a agent-local cache of Consul data.
// Cache is a agent-local cache of Consul data. Create a Cache using the
// New function. A zero-value Cache is not ready for usage and will result
// in a panic.
//
// The types of data to be cached must be registered via RegisterType. Then,
// calls to Get specify the type and a Request implementation. The
// implementation of Request is usually done directly on the standard RPC
// struct in agent/structs. This API makes cache usage a mostly drop-in
// replacement for non-cached RPC calls.
//
// The cache is partitioned by ACL and datacenter. This allows the cache
// to be safe for multi-DC queries and for queries where the data is modified
// due to ACLs all without the cache having to have any clever logic, at
// the slight expense of a less perfect cache.
//
// The Cache exposes various metrics via go-metrics. Please view the source
// searching for "metrics." to see the various metrics exposed. These can be
// used to explore the performance of the cache.
type Cache struct {
// Keeps track of the cache hits and misses in total. This is used by
// tests currently to verify cache behavior and is not meant for general

7
agent/cache/request.go vendored
View file

@ -4,7 +4,7 @@ import (
"time"
)
// Request is a cache-able request.
// Request is a cacheable request.
//
// This interface is typically implemented by request structures in
// the agent/structs package.
@ -20,6 +20,8 @@ type RequestInfo struct {
// Key is a unique cache key for this request. This key should
// absolutely uniquely identify this request, since any conflicting
// cache keys could result in invalid data being returned from the cache.
// The Key does not need to include ACL or DC information, since the
// cache already partitions by these values prior to using this key.
Key string
// Token is the ACL token associated with this request.
@ -43,6 +45,7 @@ type RequestInfo struct {
// Timeout is the timeout for waiting on a blocking query. When the
// timeout is reached, the last known value is returned (or maybe nil
// if there was no prior value).
// if there was no prior value). This "last known value" behavior matches
// normal Consul blocking queries.
Timeout time.Duration
}