groupcache package - github.com/orijtech/groupcache

groupcache package - github.com/orijtech/groupcache - Go Packages

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.

This section is empty.

View Source

var (
	MGets            = stats.Int64("gets", "The number of Get requests", unitDimensionless)
	MCacheHits       = stats.Int64("cache_hits", "The number of times that either cache was good", unitDimensionless)
	MCacheMisses     = stats.Int64("cache_misses", "The number of times that either cache was not good", unitDimensionless)
	MPeerLoads       = stats.Int64("peer_loads", "The number of remote loads or remote cache hits", unitDimensionless)
	MPeerErrors      = stats.Int64("peer_errors", "The number of remote errors", unitDimensionless)
	MLoads           = stats.Int64("loads", "The number of gets/cacheHits", unitDimensionless)
	MLoadErrors      = stats.Int64("loads_errors", "The number of errors encountered during Get", unitDimensionless)
	MLoadsDeduped    = stats.Int64("loads_deduped", "The number of loads after singleflight", unitDimensionless)
	MLocalLoads      = stats.Int64("local_loads", "The number of good local loads", unitDimensionless)
	MLocalLoadErrors = stats.Int64("local_load_errors", "The number of bad local loads", unitDimensionless)
	MServerRequests  = stats.Int64("server_requests", "The number of Gets that came over the network from peers", unitDimensionless)
	MKeyLength       = stats.Int64("key_length", "The length of keys", unitBytes)
	MValueLength     = stats.Int64("value_length", "The length of values", unitBytes)

	MRoundtripLatencyMilliseconds = stats.Float64("roundtrip_latency", "Roundtrip latency in milliseconds", unitMillisecond)
)

View Source

var AllViews = []*view.View{
	{Name: "groupcache/gets", Description: "The number of Get requests", Measure: MGets, Aggregation: view.Count()},
	{Name: "groupcache/cache_hits", Description: "The number of times that either cache was good", Measure: MCacheHits, Aggregation: view.Count()},
	{Name: "groupcache/cache_misses", Description: "The number of times that either cache was not good", Measure: MCacheMisses, Aggregation: view.Count()},
	{Name: "groupcache/peer_loads", Description: "The number of remote loads or remote cache hits", Measure: MPeerLoads, Aggregation: view.Count()},
	{Name: "groupcache/peer_errors", Description: "The number of remote errors", Measure: MPeerErrors, Aggregation: view.Count()},
	{Name: "groupcache/loads", Description: "The number of loads after singleflight", Measure: MLoads, Aggregation: view.Count()},
	{Name: "groupcache/loads_deduped", Description: "The number of loads after singleflight", Measure: MLoadsDeduped, Aggregation: view.Count()},
	{Name: "groupcache/local_loads", Description: "The number of good local loads", Measure: MLocalLoads, Aggregation: view.Count()},
	{Name: "groupcache/local_load_errors", Description: "The number of bad local loads", Measure: MLocalLoadErrors, Aggregation: view.Count()},
	{Name: "groupcache/server_requests", Description: "The number of Gets that came over the network from peers", Measure: MServerRequests, Aggregation: view.Count()},
	{Name: "groupcache/key_length", Description: "The distribution of the key lengths", Measure: MKeyLength, Aggregation: defaultBytesDistribution},
	{Name: "groupcache/value_length", Description: "The distribution of the value lengths", Measure: MValueLength, Aggregation: defaultBytesDistribution},
	{Name: "groupcache/roundtrip_latency", Description: "The roundtrip latency", Measure: MRoundtripLatencyMilliseconds, Aggregation: defaultMillisecondsDistribution},
}

func RegisterNewGroupHook(fn func(*Group))

RegisterNewGroupHook registers a hook that is run each time a group is created.

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(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(fn func())

RegisterServerStart registers a hook that is run when the first group is created.

An AtomicInt is an int64 to be accessed atomically.

Add atomically adds n to i.

Get atomically gets the value of i.

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).

At returns the byte at index i.

func (v ByteView) ByteSlice() []byte

ByteSlice returns a copy of the data as a byte slice.

Copy copies b into dest and returns the number of bytes copied.

Equal returns whether the bytes in b are the same as the bytes in b2.

EqualBytes returns whether the bytes in b are the same as the bytes in b2.

EqualString returns whether the bytes in b are the same as the bytes in s.

func (v ByteView) Len() int

Len returns the view's length.

ReadAt implements io.ReaderAt on the bytes in v.

Reader returns an io.ReadSeeker for the bytes in v.

func (v ByteView) Slice(from, to int) ByteView

Slice slices the view between the provided from and to indices.

func (v ByteView) SliceFrom(from int) ByteView

SliceFrom slices the view from the provided index until the end.

String returns the data as a string, making a copy if necessary.

WriteTo implements io.WriterTo on the bytes in v.

CacheStats are returned by stats accessors on Group.

CacheType represents a type of cache.

const (
	
	
	MainCache CacheType = iota + 1

	
	
	
	HotCache
)

A Getter loads data for a key.

A GetterFunc implements Getter with a function.

type Group struct {

	
	Stats Stats
	
}

A Group is a cache namespace and associated data loaded spread over a group of 1 or more machines.

GetGroup returns the named group previously created with NewGroup, or nil if there's no such group.

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 (g *Group) CacheStats(which CacheType) CacheStats

CacheStats returns stats about the provided cache within the group.

Name returns the name of the group.

HTTPPool implements PeerPicker for a pool of HTTP peers.

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".

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.

Set updates the pool's list of peers. Each peer value should be a valid base URL, for example "http://example.net:8000".

HTTPPoolOptions are the configurations of a HTTPPool.

NoPeers is an implementation of PeerPicker that never finds a peer.

type PeerPicker interface {
	
	
	
	PickPeer(key string) (peer ProtoGetter, ok bool)
}

PeerPicker is the interface that must be implemented to locate the peer that owns a specific key.

ProtoGetter is the interface that must be implemented by a peer.

A Sink receives data from a Get call.

Implementation of Getter must call exactly one of the Set methods on success.

func AllocatingByteSliceSink(dst *[]byte) Sink

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(dst *ByteView) Sink

ByteViewSink returns a Sink that populates a ByteView.

ProtoSink returns a sink that unmarshals binary proto values into m.

StringSink returns a Sink that populates the provided string pointer.

func TruncatingByteSliceSink(dst *[]byte) Sink

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 struct {
	Gets           AtomicInt 
	CacheHits      AtomicInt 
	PeerLoads      AtomicInt 
	PeerErrors     AtomicInt
	Loads          AtomicInt 
	LoadsDeduped   AtomicInt 
	LocalLoads     AtomicInt 
	LocalLoadErrs  AtomicInt 
	ServerRequests AtomicInt 
}

Stats are per-group statistics.