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 ¶
- func MakeGrpcPeer(host string, port uint, connections int) *grpcPeer
- func RegisterNewGroupHook(fn func(*Group))
- func RegisterPeerPicker(fn func() PeerPicker)
- func RegisterPerGroupPeerPicker(fn func(groupName string) PeerPicker)
- func RegisterServerStart(fn func())
- func SetEvictCallback(fn EvictCallbackFunction)
- func UnRegisterPeerPicker()
- func UnregisterGroup(name string)
- 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) Empty() bool
- func (v ByteView) Equal(b2 ByteView) bool
- func (v ByteView) EqualBytes(b2 []byte) bool
- func (v ByteView) EqualString(s string) bool
- 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 Context
- type DeleteFunc
- type Deleter
- type EvictCallbackFunction
- type Getter
- type GetterFunc
- type Group
- func (g *Group) CacheStats(which CacheType) CacheStats
- func (g *Group) Delete(ctx context.Context, key string) error
- func (g *Group) DeleteLocally(ctx context.Context, key string) error
- func (g *Group) Get(ctx context.Context, key string, dest Sink) error
- func (g *Group) Name() string
- func (g *Group) RegisterDeleter(fn DeleteFunc)
- func (g *Group) RegisterSetter(fn SetterFunc)
- func (g *Group) Set(ctx context.Context, key string, value ByteView) error
- func (g *Group) SetLocally(ctx context.Context, key string, value ByteView) error
- type GrpcPool
- func (s *GrpcPool) Delete(ctx context.Context, in *pb.DeleteRequest) (out *emptypb.Empty, err error)
- func (s *GrpcPool) Get(ctx context.Context, in *pb.GetRequest) (out *pb.GetResponse, err error)
- func (p *GrpcPool) PickPeer(key string) (Peer, bool)
- func (s *GrpcPool) Set(ctx context.Context, in *pb.SetRequest) (out *emptypb.Empty, err error)
- func (p *GrpcPool) SetParallelConnections(n int)
- func (p *GrpcPool) SetPeers(peers ...string)
- func (p *GrpcPool) StartGrpcServer() error
- type HTTPPool
- type HTTPPoolOptions
- type NoPeers
- type Peer
- type PeerPicker
- type Setter
- type SetterFunc
- type Sink
- type Stats
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MakeGrpcPeer ¶
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.
func SetEvictCallback ¶
func SetEvictCallback(fn EvictCallbackFunction)
func UnRegisterPeerPicker ¶
func UnRegisterPeerPicker()
UnRegisterPeerPicker allows unit tests to call RegisterPeerPicker() multiple times.
func UnregisterGroup ¶
func UnregisterGroup(name string)
Unregister unregister a group. Intended for unit tests.
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 MakeByteViewByteArray ¶
func MakeByteViewString ¶
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 DeleteFunc ¶
A DeleteFunc implements Delete with a function.
type Deleter ¶
type Deleter interface { // Delete stores the value identified by key. // // The stored data must be unversioned. That is, key must // uniquely describe the loaded data, without an implicit // current time, and without relying on cache expiration // mechanisms. Delete(ctx context.Context, key string) error }
A Deleter stores data for a key. This is optional and useful when getter functions are "expensive" in latency or other resources.
type EvictCallbackFunction ¶
Callback function to call on evictions.
var EvictCallback EvictCallbackFunction = nil
type Getter ¶
type Getter interface { // Get returns the value identified by key, populating dest. // // The returned data must be unversioned. 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.
func (*Group) RegisterDeleter ¶
func (g *Group) RegisterDeleter(fn DeleteFunc)
func (*Group) RegisterSetter ¶
func (g *Group) RegisterSetter(fn SetterFunc)
type GrpcPool ¶
type GrpcPool struct { // Replicas specifies the number of key replicas on the consistent hash. // If blank, it defaults to 50. Replicas int // HashFn specifies the hash function of the consistent hash. // If blank, it defaults to crc32.ChecksumIEEE. HashFn consistenthash.Hash // contains filtered or unexported fields }
GrpcPool implements PeerPicker for a pool of gRPC peers.
func NewGrpcPool ¶
NewGrpcPool initializes a gRPC pool of peers, and registers itself as a PeerPicker. The self argument should be a valid host:port pair that points to the current server, for example "hostname1:1234".
func NewLocalGrpcPool ¶
NewLocalGrpcPool initializes a gRPC pool for local use only. There are no remote peers.
func NewRemoteGrpcPool ¶
func NewRemoteGrpcPool() *GrpcPool
NewRemoteGrpcPool initializes a gRPC pool for a remote set of peers. There is no local server: calls are always forwarded to remote servers.
func (*GrpcPool) Get ¶
func (s *GrpcPool) Get(ctx context.Context, in *pb.GetRequest) (out *pb.GetResponse, err error)
func (*GrpcPool) SetParallelConnections ¶
func (*GrpcPool) SetPeers ¶
SetPeers updates the pool's list of peers. Valid examples: "1.2.3.4", "2.2.2.2:2000", "host1:3000".
func (*GrpcPool) StartGrpcServer ¶
StartGrpcServer starts the gRPC server.
type HTTPPool ¶
type HTTPPool struct { // Context optionally specifies a context for the server to use when it // receives a request. // If nil, the server uses the request's context Context func(*http.Request) context.Context // Transport optionally specifies an http.RoundTripper for the client // to use when it makes a request. // If nil, the client uses http.DefaultTransport. Transport func(context.Context) http.RoundTripper // contains filtered or unexported fields }
HTTPPool implements PeerPicker for a pool of HTTP peers.
func NewHTTPPool ¶
NewHTTPPool initializes an HTTP pool of peers, and registers itself as a PeerPicker. For convenience, it also registers itself as an http.Handler with http.DefaultServeMux. The self argument should be a valid base URL that points to the current server, for example "http://example.net:8000".
func NewHTTPPoolOpts ¶
func NewHTTPPoolOpts(self string, o *HTTPPoolOptions) *HTTPPool
NewHTTPPoolOpts initializes an HTTP pool of peers with the given options. Unlike NewHTTPPool, this function does not register the created pool as an HTTP handler. The returned *HTTPPool implements http.Handler and must be registered using http.Handle.
func (*HTTPPool) Set ¶
Set updates the pool's list of peers. Each peer value should be a valid base URL, for example "http://example.net:8000".
type HTTPPoolOptions ¶
type HTTPPoolOptions struct { // GetPath specifies the HTTP path that will serve groupcache get requests. // If blank, it defaults to "/_groupcache/". GetPath string // SetPath specifies the HTTP path that will serve groupcache set requests. // If blank, it defaults to "/_set_groupcache/". SetPath string // SetPath specifies the HTTP path that will serve groupcache delete // requests. If blank, it defaults to "/_delete_groupcache/". DeletePath string // Replicas specifies the number of key replicas on the consistent hash. // If blank, it defaults to 50. Replicas int // HashFn specifies the hash function of the consistent hash. // If blank, it defaults to crc32.ChecksumIEEE. HashFn consistenthash.Hash }
HTTPPoolOptions are the configurations of a HTTPPool.
type NoPeers ¶
type NoPeers struct{}
NoPeers is an implementation of PeerPicker that never finds a peer.
type Peer ¶
type Peer interface { Get(ctx context.Context, in *pb.GetRequest, out *pb.GetResponse) error Set(ctx context.Context, in *pb.SetRequest, out *emptypb.Empty) error Delete(ctx context.Context, in *pb.DeleteRequest, out *emptypb.Empty) error }
Peer is the interface that must be implemented by a peer.
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 Peer, ok bool) }
PeerPicker is the interface that must be implemented to locate the peer that owns a specific key.
type Setter ¶
type Setter interface { // Set stores the value identified by key. // // The stored data must be unversioned. That is, key must // uniquely describe the loaded data, without an implicit // current time, and without relying on cache expiration // mechanisms. Set(ctx context.Context, key string, value ByteView) error }
A Setter stores data for a key. This is optional and useful when getter functions are "expensive" in latency or other resources.
type SetterFunc ¶
A SetterFunc implements Setter with a function.
type Sink ¶
type Sink interface { // SetString sets the value to s. SetString(s string) error // SetBytes sets the value to the contents of v. // The caller retains ownership of v. SetBytes(v []byte) error // SetProto sets the value to the encoded version of m. // The caller retains ownership of m. SetProto(m proto.Message) 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.
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 Sets AtomicInt // any Set (store) request, including from peers Deletes AtomicInt // any Delete request, including from peers CacheHits AtomicInt // either cache was good PeerLoads AtomicInt // either remote load or remote cache hit (not an error) PeerStores AtomicInt // remote store (not an error) PeerDeletes AtomicInt // remote deletes (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 LocalSets AtomicInt // local local set operations LocalSetErrs AtomicInt // total local set errors LocalDeletes AtomicInt // local local set operations LocalDeleteErrs AtomicInt // total local set errors ServerRequests AtomicInt // gets that came over the network from peers }
Stats are per-group statistics.
Directories
¶
Path | Synopsis |
---|---|
Package consistenthash provides an implementation of a ring hash.
|
Package consistenthash provides an implementation of a ring hash. |
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. |