Documentation ¶
Overview ¶
Package groupcache provides a data loading mechanism with caching and de-duplication that works across a set of peer processes.
Each data Get first consults its local cache, otherwise delegates to the requested key's canonical owner, which then checks its cache or finally gets the data. In the common case, many concurrent cache misses across a set of peers for the same key result in just one cache fill.
Index ¶
- Variables
- func DeregisterGroup(name string)
- func RegisterNewGroupHook(fn func(*Group))
- func RegisterPeerPicker(fn func() PeerPicker)
- func RegisterPerGroupPeerPicker(fn func(groupName string) PeerPicker)
- func RegisterServerStart(fn func())
- type AtomicInt
- type ByteView
- func (v ByteView) At(i int) byte
- func (v ByteView) ByteSlice() []byte
- func (v ByteView) Copy(dest []byte) int
- func (v ByteView) Equal(b2 ByteView) bool
- func (v ByteView) EqualBytes(b2 []byte) bool
- func (v ByteView) EqualString(s string) bool
- func (v ByteView) Expire() time.Time
- func (v ByteView) Len() int
- func (v ByteView) ReadAt(p []byte, off int64) (n int, err error)
- func (v ByteView) Reader() io.ReadSeeker
- func (v ByteView) Slice(from, to int) ByteView
- func (v ByteView) SliceFrom(from int) ByteView
- func (v ByteView) String() string
- func (v ByteView) WriteTo(w io.Writer) (n int64, err error)
- type CacheStats
- type CacheType
- type ErrNotFound
- type ErrRemoteCall
- type Getter
- type GetterFunc
- type Group
- func (g *Group) CacheStats(which CacheType) CacheStats
- func (g *Group) Get(ctx context.Context, key string, dest Sink) error
- func (g *Group) Name() string
- func (g *Group) Remove(ctx context.Context, key string) error
- func (g *Group) Set(ctx context.Context, key string, value []byte, expire time.Time, hotCache bool) error
- type Interface
- type NoPeers
- type Node
- type Option
- type OptionFunc
- type PeerPicker
- type ProtoGetter
- type Sink
- type Stats
Constants ¶
This section is empty.
Variables ¶
var NowFunc lru.NowFunc = time.Now
NowFunc returns the current time which is used by the LRU to determine if the value has expired. This can be overridden by tests to ensure items are evicted when expired.
Functions ¶
func DeregisterGroup ¶
func DeregisterGroup(name string)
DeregisterGroup removes group from group pool
func RegisterNewGroupHook ¶
func RegisterNewGroupHook(fn func(*Group))
RegisterNewGroupHook registers a hook that is run each time a group is created.
func RegisterPeerPicker ¶
func RegisterPeerPicker(fn func() PeerPicker)
RegisterPeerPicker registers the peer initialization function. It is called once, when the first group is created. Either RegisterPeerPicker or RegisterPerGroupPeerPicker should be called exactly once, but not both.
func RegisterPerGroupPeerPicker ¶
func RegisterPerGroupPeerPicker(fn func(groupName string) PeerPicker)
RegisterPerGroupPeerPicker registers the peer initialization function, which takes the groupName, to be used in choosing a PeerPicker. It is called once, when the first group is created. Either RegisterPeerPicker or RegisterPerGroupPeerPicker should be called exactly once, but not both.
func RegisterServerStart ¶
func RegisterServerStart(fn func())
RegisterServerStart registers a hook that is run when the first group is created.
Types ¶
type ByteView ¶
type ByteView struct {
// contains filtered or unexported fields
}
A ByteView holds an immutable view of bytes. Internally it wraps either a []byte or a string, but that detail is invisible to callers.
A ByteView is meant to be used as a value type, not a pointer (like a time.Time).
func (ByteView) EqualBytes ¶
EqualBytes returns whether the bytes in b are the same as the bytes in b2.
func (ByteView) EqualString ¶
EqualString returns whether the bytes in b are the same as the bytes in s.
func (ByteView) Reader ¶
func (v ByteView) Reader() io.ReadSeeker
Reader returns an io.ReadSeeker for the bytes in v.
type CacheStats ¶
CacheStats are returned by stats accessors on Group.
type ErrNotFound ¶
type ErrNotFound struct {
Msg string
}
ErrNotFound should be returned from an implementation of `GetterFunc` to indicate the requested value is not available. When remote HTTP calls are made to retrieve values from other groupcache instances, returning this error will indicate to groupcache that the value requested is not available, and it should NOT attempt to call `GetterFunc` locally.
func (*ErrNotFound) Error ¶
func (e *ErrNotFound) Error() string
func (*ErrNotFound) Is ¶
func (e *ErrNotFound) Is(target error) bool
type ErrRemoteCall ¶
type ErrRemoteCall struct {
Msg string
}
ErrRemoteCall is returned from `group.Get()` when a remote GetterFunc returns an error. When this happens `group.Get()` does not attempt to retrieve the value via our local GetterFunc.
func (*ErrRemoteCall) Error ¶
func (e *ErrRemoteCall) Error() string
func (*ErrRemoteCall) Is ¶
func (e *ErrRemoteCall) Is(target error) bool
type Getter ¶
type Getter interface { // Get returns the value identified by key, populating dest. // // The returned data must be un-versioned. That is, key must // uniquely describe the loaded data, without an implicit // current time, and without relying on cache expiration // mechanisms. Get(ctx context.Context, key string, dest Sink) error }
A Getter loads data for a key.
type GetterFunc ¶
A GetterFunc implements Getter with a function.
type Group ¶
type Group struct { // Stats are statistics on the group. Stats Stats // contains filtered or unexported fields }
A Group is a cache namespace and associated data loaded spread over a group of 1 or more machines.
func GetGroup ¶
GetGroup returns the named group previously created with NewGroup, or nil if there's no such group.
func NewGroup ¶
NewGroup creates a coordinated group-aware Getter from a Getter.
The returned Getter tries (but does not guarantee) to run only one Get call at once for a given key across an entire set of peer processes. Concurrent callers both in the local process and in other processes receive copies of the answer once the original Get completes.
The group name must be unique for each getter.
func (*Group) CacheStats ¶
func (g *Group) CacheStats(which CacheType) CacheStats
CacheStats returns stats about the provided cache within the group.
type Interface ¶
type Interface interface { // Start starts the Node engine Start(ctx context.Context) error // Stop stops the Node engine Stop(ctx context.Context) error }
Interface defines the Node interface
type NoPeers ¶
type NoPeers struct{}
NoPeers is an implementation of PeerPicker that never finds a peer.
func (NoPeers) GetAll ¶
func (NoPeers) GetAll() []ProtoGetter
type Node ¶
type Node struct {
// contains filtered or unexported fields
}
type Option ¶
type Option interface { // Apply sets the Option value of a config. Apply(node *Node) }
func WithHashFn ¶
func WithHashFn(hashFn consistenthash.Hash) Option
WithHashFn sets the custom hash function
func WithReplicaCount ¶
WithReplicaCount sets the total number of replicas count
func WithShutdownTimeout ¶
WithShutdownTimeout sets the shutdown timeout
type PeerPicker ¶
type PeerPicker interface { // PickPeer returns the peer that owns the specific key // and true to indicate that a remote peer was nominated. // It returns nil, false if the key owner is the current peer. PickPeer(key string) (peer ProtoGetter, ok bool) // GetAll returns all the peers in the group GetAll() []ProtoGetter }
PeerPicker is the interface that must be implemented to locate the peer that owns a specific key.
type ProtoGetter ¶
type ProtoGetter interface { Get(context context.Context, in *pb.GetRequest, out *pb.GetResponse) error Remove(context context.Context, in *pb.GetRequest) error Set(context context.Context, in *pb.SetRequest) error // GetURL returns the peer URL GetURL() string }
ProtoGetter is the interface that must be implemented by a peer.
type Sink ¶
type Sink interface { // SetString sets the value to s. SetString(s string, e time.Time) error // SetBytes sets the value to the contents of v. // The caller retains ownership of v. SetBytes(v []byte, e time.Time) error // SetProto sets the value to the encoded version of m. // The caller retains ownership of m. SetProto(m proto.Message, e time.Time) error // contains filtered or unexported methods }
A Sink receives data from a Get call.
Implementation of Getter must call exactly one of the Set methods on success.
`e` sets an optional time in the future when the value will expire. If you don't want expiration, pass the zero value for `time.Time` (for instance, `time.Time{}`).
func AllocatingByteSliceSink ¶
AllocatingByteSliceSink returns a Sink that allocates a byte slice to hold the received value and assigns it to *dst. The memory is not retained by groupcache.
func ByteViewSink ¶
ByteViewSink returns a Sink that populates a ByteView.
func StringSink ¶
StringSink returns a Sink that populates the provided string pointer.
func TruncatingByteSliceSink ¶
TruncatingByteSliceSink returns a Sink that writes up to len(*dst) bytes to *dst. If more bytes are available, they're silently truncated. If fewer bytes are available than len(*dst), *dst is shrunk to fit the number of bytes available.
type Stats ¶
type Stats struct { Gets AtomicInt // any Get request, including from peers CacheHits AtomicInt // either cache was good GetFromPeersLatencyLower AtomicInt // slowest duration to request value from peers PeerLoads AtomicInt // either remote load or remote cache hit (not an error) PeerErrors AtomicInt Loads AtomicInt // (gets - cacheHits) LoadsDeduped AtomicInt // after singleflight LocalLoads AtomicInt // total good local loads LocalLoadErrs AtomicInt // total bad local loads ServerRequests AtomicInt // gets that came over the network from peers }
Stats are per-group statistics.
Source Files ¶
Directories ¶
Path | Synopsis |
---|---|
Package consistenthash provides an implementation of a ring hash.
|
Package consistenthash provides an implementation of a ring hash. |
Package discovery provides the interface to discover other groupcache nodes in the cluster
|
Package discovery provides the interface to discover other groupcache nodes in the cluster |
kubernetes
Package kubernetes defines the kubernetes discovery provider
|
Package kubernetes defines the kubernetes discovery provider |
mdns
Package mdns defines the mdns discovery provider
|
Package mdns defines the mdns discovery provider |
example
|
|
Package lru implements an LRU cache.
|
Package lru implements an LRU cache. |
Package singleflight provides a duplicate function call suppression mechanism.
|
Package singleflight provides a duplicate function call suppression mechanism. |