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)
-
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 提供了一个缓存的数据加载机制， and de-duplication that works across a set of peer processes.
每一个数据都会首先向本地缓存获取数据，否则会向数据的拥有者获取 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 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) 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 Getter
- type GetterFunc
- type Group
- type HTTPPool
- type HTTPPoolOptions
- 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.
func RegisterPeerPicker ¶
func RegisterPeerPicker(fn func() PeerPicker)
RegisterPeerPicker 注册一个peer初始化的方法 当第一个group被创建的时候，它就会被调用一次 RegisterPeerPicker和RegisterPerGroupPeerPicker都只能被调用一次
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注册了一个钩子，他会在第一个group被创建的时候运行
Types ¶
type ByteView ¶
type ByteView struct {
// contains filtered or unexported fields
}
A ByteView 是被用来作为一个value类型的，而不是一个指针类型 (例如 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 Getter ¶
type Getter interface {
// Get returns the value identified by key, populating dest.
// 返回的数据必须是未版本化的。 也就是说，密钥必须唯一地描述加载的数据，没有隐式当前时间，并且不依赖于缓存过期机制。
Get(ctx context.Context, key string, dest Sink) error
}
获取key的数据
type GetterFunc ¶
A GetterFunc 实现了Getter接口
type Group ¶
type Group struct {
// Stats 是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. Group 是一个缓存的命名空间，同时将相关联的数据加载后同步到一组机器（1个或多个机器组成）中
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 HTTPPool ¶
type HTTPPool struct {
// Context是一个可选的配置，他是当收到request的时候，供server使用的，如果没有设置，就使用request的中的context
Context func(*http.Request) context.Context
// 当创建一个request的时候，可以指定一个http.RoundTripper供client使用。如果没有设置，就使用默认的http.DefaultTransport
Transport func(context.Context) http.RoundTripper
// contains filtered or unexported fields
}
HTTPPool implements PeerPicker for a pool of HTTP peers. HTTPPool是实现了PeerPicker接口的一个HTTP连接池
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 ¶
更新pool中peers列表,每一个peer必须是一个合法的URL for example "http://example.net:8000".
type HTTPPoolOptions ¶
type HTTPPoolOptions struct {
// BasePath 指定了处理groupcache的请求的 HTTP 地址
// 如果没有设置，就使用默认值: "/_groupcache/".
BasePath string
// 指定了在一致性hash中key的副本数量，如果没有设置，就使用默认值50
Replicas int
// 用于生成一致性hash值的方法，如果没有设置，就使用crc32.ChecksumIEEE.
HashFn consistenthash.Hash
}
HTTPPoolOptions 是HTTPPool的配置项.
type PeerPicker ¶
type PeerPicker interface {
// PickPeer 返回通过key找到的peer，returns the peer that owns the specific key
// and返回true的话表明有一个远端的peer被找到， true to indicate that a remote peer was nominated.
// 如果通过key找到的peer是本地peer的话，就返回nil和false
PickPeer(key string) (peer ProtoGetter, ok bool)
}
PeerPicker 是一个接口，它必须被本地的拥有指定key的peer实现 is the interface that must be implemented to locate the peer that owns a specific key.
type ProtoGetter ¶
type ProtoGetter interface {
Get(ctx context.Context, in *pb.GetRequest, out *pb.GetResponse) error
}
ProtoGetter 是一个接口，peer必须实现这个接口
type Sink ¶
type Sink interface {
// SetString 将值设置为一个string
SetString(s string) error
// SetBytes sets the value to the contents of v.
// SetBytes将值设置为[]byte
// The caller retains ownership of v.
// 调用者保留对v的所有权
SetBytes(v []byte) error
// SetProto sets the value to the encoded version of m.
// The caller retains ownership of m.
// SetProto 将值设置为已经编码后的m
SetProto(m proto.Message) error
// contains filtered or unexported methods
}
stringSink、byteViewSink、protoSink、allocBytesSink都实现了Sink接口
func AllocatingByteSliceSink ¶
AllocatingByteSliceSink returns a Sink that allocates a byte slice to hold the received value and assigns it to *dst. 这个内存是不被groupcache保留的
func ByteViewSink ¶
ByteViewSink returns a Sink that populates a ByteView.
func StringSink ¶
StringSink returns a Sink that populates the provided string pointer. 返回的是已提供的string的指针
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 // 任何的Get请求，包括来自peers的Get
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 通过网络从peers获得请求的数量
}
Stats 是每一个group的统计信息
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
hash 环的一个实现
|
hash 环的一个实现 |
|
Package lru 实现了一个lru缓存
|
Package lru 实现了一个lru缓存 |
|
Package singleflight 提供了重复调用函数时的抑制机制
|
Package singleflight 提供了重复调用函数时的抑制机制 |