Categorygithub.com/golang/groupcache
modulepackage
0.0.0-20241129210726-2c02b8208cf8
Repository: https://github.com/golang/groupcache.git
Documentation: pkg.go.dev
Versions
1
Dependencies
17
Dependents
63
Files
1k SLOC

# README

groupcache

Summary

groupcache is a distributed caching and cache-filling library, intended as a replacement for a pool of memcached nodes in many cases.

For API docs and examples, see http://godoc.org/github.com/golang/groupcache

Comparison to memcached

Like memcached, groupcache:

  • shards by key to select which peer is responsible for that key

Unlike memcached, groupcache:

  • does not require running a separate set of servers, thus massively reducing deployment/configuration pain. groupcache is a client library as well as a server. It connects to its own peers, forming a distributed cache.

  • comes with a cache filling mechanism. Whereas memcached just says "Sorry, cache miss", often resulting in a thundering herd of database (or whatever) loads from an unbounded number of clients (which has resulted in several fun outages), groupcache coordinates cache fills such that only one load in one process of an entire replicated set of processes populates the cache, then multiplexes the loaded value to all callers.

  • does not support versioned values. If key "foo" is value "bar", key "foo" must always be "bar". There are neither cache expiration times, nor explicit cache evictions. Thus there is also no CAS, nor Increment/Decrement. This also means that groupcache....

  • ... supports automatic mirroring of super-hot items to multiple processes. This prevents memcached hot spotting where a machine's CPU and/or NIC are overloaded by very popular keys/values.

  • is currently only available for Go. It's very unlikely that I (bradfitz@) will port the code to any other language.

Loading process

In a nutshell, a groupcache lookup of Get("foo") looks like:

(On machine #5 of a set of N machines running the same code)

  1. Is the value of "foo" in local memory because it's super hot? If so, use it.

  2. Is the value of "foo" in local memory because peer #5 (the current peer) is the owner of it? If so, use it.

  3. Amongst all the peers in my set of N, am I the owner of the key "foo"? (e.g. does it consistent hash to 5?) If so, load it. If other callers come in, via the same process or via RPC requests from peers, they block waiting for the load to finish and get the same answer. If not, RPC to the peer that's the owner and get the answer. If the RPC fails, just load it locally (still with local dup suppression).

Users

groupcache is in production use by dl.google.com (its original user), parts of Blogger, parts of Google Code, parts of Google Fiber, parts of Google production monitoring systems, etc.

Presentations

See http://talks.golang.org/2013/oscon-dl.slide

Help

Use the golang-nuts mailing list for any discussion or questions.

# Packages

Package consistenthash provides an implementation of a ring hash.
Package lru implements an LRU cache.
Package singleflight provides a duplicate function call suppression mechanism.

# Functions

AllocatingByteSliceSink returns a Sink that allocates a byte slice to hold the received value and assigns it to *dst.
ByteViewSink returns a Sink that populates a ByteView.
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.
NewHTTPPool initializes an HTTP pool of peers, and registers itself as a PeerPicker.
NewHTTPPoolOpts initializes an HTTP pool of peers with the given options.
ProtoSink returns a sink that unmarshals binary proto values into m.
RegisterNewGroupHook registers a hook that is run each time a group is created.
RegisterPeerPicker registers the peer initialization function.
RegisterPerGroupPeerPicker registers the peer initialization function, which takes the groupName, to be used in choosing a PeerPicker.
RegisterServerStart registers a hook that is run when the first group is created.
StringSink returns a Sink that populates the provided string pointer.
TruncatingByteSliceSink returns a Sink that writes up to len(*dst) bytes to *dst.

# Constants

The HotCache is the cache for items that seem popular enough to replicate to this node, even though it's not the owner.
The MainCache is the cache for items that this peer is the owner for.

# Structs

A ByteView holds an immutable view of bytes.
CacheStats are returned by stats accessors on Group.
A Group is a cache namespace and associated data loaded spread over a group of 1 or more machines.
HTTPPool implements PeerPicker for a pool of HTTP peers.
HTTPPoolOptions are the configurations of a HTTPPool.
NoPeers is an implementation of PeerPicker that never finds a peer.
Stats are per-group statistics.

# Interfaces

A Getter loads data for a key.
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.

# Type aliases

An AtomicInt is an int64 to be accessed atomically.
CacheType represents a type of cache.
Context is an alias to context.Context for backwards compatibility purposes.
A GetterFunc implements Getter with a function.