groupcache

README

groupcache

Local-only nearly public API-compatible fork of github.com/golang/groupcache with removed remote peers and Protocol Buffers support.

See https://github.com/golang/groupcache.

Documentation

Overview

Package groupcache provides a data loading mechanism with caching and de-duplication.

Index

• func RegisterNewGroupHook(fn func(*Group))
• type AtomicInt
  • func (i *AtomicInt) Add(n int64)
  • func (i *AtomicInt) Get() int64
  • func (i *AtomicInt) String() string
• 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 Getter
• type GetterFunc
  • func (f GetterFunc) Get(ctx context.Context, key string, dest Sink) error
• type Group
  • func GetGroup(name string) *Group
  • func NewGroup(name string, cacheBytes int64, getter Getter) *Group
  • func (g *Group) CacheStats(which CacheType) CacheStats
  • func (g *Group) Get(ctx context.Context, key string, dest Sink) error
  • func (g *Group) Name() string
• type Sink
  • func AllocatingByteSliceSink(dst *[]byte) Sink
  • func ByteViewSink(dst *ByteView) Sink
  • func StringSink(sp *string) Sink
  • func TruncatingByteSliceSink(dst *[]byte) Sink
• type Stats

Functions

func RegisterNewGroupHook

func RegisterNewGroupHook(fn func(*Group))

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

Types

type AtomicInt

type AtomicInt int64

An AtomicInt is an int64 to be accessed atomically.

func (*AtomicInt) Add

func (i *AtomicInt) Add(n int64)

Add atomically adds n to i.

func (*AtomicInt) Get

func (i *AtomicInt) Get() int64

Get atomically gets the value of i.

func (*AtomicInt) String

func (i *AtomicInt) String() string

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 (ByteView) At

func (v ByteView) At(i int) byte

At returns the byte at index i.

func (ByteView) ByteSlice

func (v ByteView) ByteSlice() []byte

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

func (ByteView) Copy

func (v ByteView) Copy(dest []byte) int

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

func (ByteView) Equal

func (v ByteView) Equal(b2 ByteView) bool

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

func (ByteView) EqualBytes

func (v ByteView) EqualBytes(b2 []byte) bool

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

func (ByteView) EqualString

func (v ByteView) EqualString(s string) bool

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

func (ByteView) Len

func (v ByteView) Len() int

Len returns the view's length.

func (ByteView) ReadAt

func (v ByteView) ReadAt(p []byte, off int64) (n int, err error)

ReadAt implements io.ReaderAt on the bytes in v.

func (ByteView) Reader

func (v ByteView) Reader() io.ReadSeeker

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

func (ByteView) Slice

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

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

func (ByteView) SliceFrom

func (v ByteView) SliceFrom(from int) ByteView

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

func (ByteView) String

func (v ByteView) String() string

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

func (ByteView) WriteTo

func (v ByteView) WriteTo(w io.Writer) (n int64, err error)

WriteTo implements io.WriterTo on the bytes in v.

type CacheStats

type CacheStats struct {
	Bytes     int64
	Items     int64
	Gets      int64
	Hits      int64
	Evictions int64
}

CacheStats are returned by stats accessors on Group.

type CacheType

type CacheType int

CacheType represents a type of cache.

const (
	// The MainCache is the cache for items that this peer is the
	// owner for.
	MainCache CacheType = iota + 1

	// Deprecated: for backward compatibility only.
	// Calling (*group).CacheStats(HotCache) will return empty CacheStats.
	HotCache
)

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

type GetterFunc func(ctx context.Context, key string, dest Sink) error

A GetterFunc implements Getter with a function.

func (GetterFunc) Get

func (f GetterFunc) Get(ctx context.Context, key string, dest Sink) error

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

func GetGroup(name string) *Group

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

func NewGroup

func NewGroup(name string, cacheBytes int64, getter Getter) *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. Concurrent callers 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) Get

func (g *Group) Get(ctx context.Context, key string, dest Sink) error

func (*Group) Name

func (g *Group) Name() string

Name returns the name of the group.

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
	// 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

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

func ByteViewSink(dst *ByteView) Sink

ByteViewSink returns a Sink that populates a ByteView.

func StringSink

func StringSink(sp *string) Sink

StringSink returns a Sink that populates the provided string pointer.

func TruncatingByteSliceSink

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

type Stats struct {
	Gets           AtomicInt // any Get request
	CacheHits      AtomicInt // either cache was good
	PeerLoads      AtomicInt // Deprecated: for backward compatibility returns 0. Either remote load or remote cache hit (not an error).
	PeerErrors     AtomicInt // Deprecated: for backward compatibility returns 0.
	Loads          AtomicInt // (gets - cacheHits)
	LoadsDeduped   AtomicInt // after singleflight
	LocalLoads     AtomicInt // total good local loads
	LocalLoadErrs  AtomicInt // total bad local loads
	ServerRequests AtomicInt // Deprecated: for backward compatibility returns 0. Gets that came over the network from peers.
}

Stats are per-group statistics.