README
¶
groupcache
Summary
groupcache is a caching and cache-filling library, intended as a replacement for memcached 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.
-
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)
-
Is the value of "foo" in local memory because it's super hot? If so, use it.
-
Is the value of "foo" in local memory because peer #5 (the current peer) is the owner of it? If so, use it.
-
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.
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 RegisterNewGroupHook(fn func(*Group))
- func RegisterPeerPicker(fn func() 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) 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
- type CacheStats
- type CacheType
- type Context
- type Getter
- type GetterFunc
- type Group
- type HTTPPool
- type NoPeers
- type PeerPicker
- type ProtoGetter
- type Sink
- type Stats
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RegisterNewGroupHook ¶
func RegisterNewGroupHook(fn func(*Group))
RegisterNewGroupHook registers a hook that is run each time a group is created. 注册一个创建新group的钩子，比如将group打印出来等，全局只能注册一次，多次注册会触发panic
func RegisterPeerPicker ¶
func RegisterPeerPicker(fn func() PeerPicker)
RegisterPeerPicker registers the peer initialization function. It is called once, when the first group is created.
func RegisterServerStart ¶
func RegisterServerStart(fn func())
RegisterServerStart registers a hook that is run when the first group is created. 注册一个服务，该服务在NewGroup开始时被调用，并且只被调用一次
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). 一个不可变byte视图，其实就包装了一下byte数组和string，一个为null，就用另外一个
func (ByteView) Copy ¶
Copy copies b into dest and returns the number of bytes copied. 将ByteView按[]byte拷贝出来
func (ByteView) Equal ¶
Equal returns whether the bytes in b are the same as the bytes in b2. 判断2个ByteView是否相等
func (ByteView) EqualBytes ¶
EqualBytes returns whether the bytes in b are the same as the bytes in b2. 判断ByteView是否和[]byte相等
func (ByteView) EqualString ¶
EqualString returns whether the bytes in b are the same as the bytes in s. 判断ByteView是否和string相等
func (ByteView) ReadAt ¶
ReadAt implements io.ReaderAt on the bytes in v. 读取从off开始的后面的数据，其实下面调用的SliceFrom，这是封装成了io.Reader的一个ReadAt方法的形式
func (ByteView) Reader ¶
func (v ByteView) Reader() io.ReadSeeker
Reader returns an io.ReadSeeker for the bytes in v. 对ByteView创建一个io.ReadSeeker
func (ByteView) Slice ¶
Slice slices the view between the provided from and to indices. 返回ByteView的某个片断，不拷贝
type CacheStats ¶
type CacheStats struct {
Bytes int64 //大小
Items int64 //缓存项数量
Gets int64 //请求次数
Hits int64 //命中次数
Evictions int64
}
CacheStats are returned by stats accessors on Group. 缓存统计信息
type Context ¶
type Context interface{}
Context is an opaque value passed through calls to the ProtoGetter. It may be nil if your ProtoGetter implementation does not require a context.
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, 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. 该类是GroupCache的核心类，所有的其他包都是为该类服务的。groupcache支持namespace概念，不同的namespace有自己的配额以及cache， 不同group之间cache是独立的也就是不能存在某个group的行为影响到另外一个namespace的情况 groupcache的每个节点的cache分为2层， 由本节点直接访问后端的存在maincache，其他存在在hotcache
func GetGroup ¶
GetGroup returns the named group previously created with NewGroup, or nil if there's no such group. 根据name从全局变量groups（一个string/group的map）查找对于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. 创建一个新的group，如果已经存在该name的group将会抛出一个异常，go里面叫panic
func (*Group) CacheStats ¶
func (g *Group) CacheStats(which CacheType) CacheStats
CacheStats returns stats about the provided cache within the group.
func (*Group) Get ¶
整个groupcache核心方法就这么一个 这里需要说明的是A向groupcache中其他节点B发送请求，此时B是调用Get方法，然后如果本地不存在则也会走load，但是不同的是 PickPeer会发现是本身节点（HTTPPOOL的实现），然后就会走getLocally，会将数据在B的maincache中填充一份，也就是说如果 是向groupcache中其他节点发请求的，会一下子在groupcache集群内存2分数据，一份在B的maincache里，一份在A的hotcache中， 这也就达到了自动复制，越是热点的数据越是在集群内份数多，也就达到了解决热点数据的问题
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 a nil Context.
Context func(*http.Request) 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) 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. It registers itself as a PeerPicker and as an HTTP handler with the http.DefaultServeMux. The self argument be a valid base URL that points to the current server, for example "http://example.net:8000". 创建一个HttpPool, 只能被使用一次，主要是注册PeerPicker，以及初始化http服务
func (*HTTPPool) PickPeer ¶
func (p *HTTPPool) PickPeer(key string) (ProtoGetter, bool)
根据key从远方获取value 提供按key选取节点，按key作hash，但是这段代码在OS为32bit是存在bug，如果算出来的hashcode正好是-1 * 2^31时 会导致out of range，为啥会有这个bug看看代码你就会发现了，作者忘了-1 * 2^31 <= int32 <= 1 * 2^31 -1
func (*HTTPPool) ServeHTTP ¶
func (p *HTTPPool) ServeHTTP(w http.ResponseWriter, r *http.Request)
http服务处理函数，主要是按http://example.com/groupname/key解析请求，调用group.Get，按协议返回请求
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". 设置groupcache集群的节点列表
type NoPeers ¶
type NoPeers struct{}
NoPeers is an implementation of PeerPicker that never finds 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 ProtoGetter, ok bool)
}
PeerPicker is the interface that must be implemented to locate the peer that owns a specific key. 接口PeerPicker表示一个路由器，PickPeer方法将给定key路由到其归属的远端节点，如果key归属于本节点，PickPeer方法返回nil。
type ProtoGetter ¶
type ProtoGetter interface {
Get(context Context, in *pb.GetRequest, out *pb.GetResponse) error
}
ProtoGetter is the interface that must be implemented by a peer. 表示一个远端节点，Get方法从远端节点查询数据
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
CacheHits AtomicInt // either cache was good
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. |
|
groupcache的protobuf协议，由程序根据groupcache.proto自动生成的代码。
|
groupcache的protobuf协议，由程序根据groupcache.proto自动生成的代码。 |
|
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(机制). |