cache

Documentation

Index

• Variables
• func ValidateValidable(key, value interface{}) (isValid bool, err error)
• type Cache
  • func NewLoader(f LoaderFunc, opts ...Option) Cache
  • func NewMemoryStorage(opts ...Option) Cache
  • func NewVoidStorage(opts ...Option) Cache
  • func SingleFlight(c Cache) Cache
• type Clock
• type Event
• type EventType
  • func (e EventType) GoString() string
  • func (e EventType) String() string
• type EvictionFactory
• type EvictionStrategy
  • func NewLFUEviction() EvictionStrategy
  • func NewLRUEviction() EvictionStrategy
• type LoaderFunc
• type Option
  • func Emitter(ch chan<- Event) Option
  • func Eviction(maxLen int, f EvictionFactory) Option
  • func Expiration(ttl time.Duration) Option
  • func ExpirationUsingClock(ttl time.Duration, cl Clock) Option
  • func LFUEviction(maxLen int) Option
  • func LRUEviction(maxLen int) Option
  • func Loader(f LoaderFunc) Option
  • func LogErrors(f Printf) Option
  • func Name(name string) Option
  • func Spy(f Printf) Option
  • func Validate(f ValidatorFunc) Option
  • func WriteThrough(outer Cache) Option
• type Printf
• type Validable
• type ValidatorFunc

Variables

var ErrKeyNotFound = errors.New("Key not found")

ErrKeyNotFound is returned by Cache.Get*() whenever the key is not present in the cache.

Functions

func ValidateValidable

func ValidateValidable(key, value interface{}) (isValid bool, err error)

ValidateValidable is a ValidatorFunc that handles Validable.

Types

type Cache

type Cache interface {
	// The string representation should be human-readable. It is used by Spy().
	fmt.Stringer

	// Put stores an entry into the cache.
	Put(key, value interface{}) error

	// Get fetchs an entry from the cache.
	// It returns nil and ErrKeyNotFound when the key is not present.
	Get(key interface{}) (value interface{}, err error)

	// Remove removes an entry from the cache.
	// It returns whether the entry was actually found and removed.
	Remove(key interface{}) bool

	// Flush instructs the cache to finish all pending operations, if any.
	// It must not return before all pending operations are finished.
	Flush() error

	// Len returns the number of entries in the cache.
	Len() int
}

Cache is the main abstraction.

func NewLoader

func NewLoader(f LoaderFunc, opts ...Option) Cache

NewLoader creates a pseudo-cache from a LoaderFunc.

func NewMemoryStorage

func NewMemoryStorage(opts ...Option) Cache

NewMemoryStorage creates an empty cache using a map and a sync.RWMutex.

func NewVoidStorage

func NewVoidStorage(opts ...Option) Cache

NewVoidStorage returns a cache that does not store nor return any entries, but can be used for side effects of options.

func SingleFlight

func SingleFlight(c Cache) Cache

SingleFlight adds a layer that deduplicates Get queries from concurrent goroutines.

type Clock

type Clock interface {
	Now() time.Time
}

Clock is a simple clock abstraction to be used with ExpirationUsingClock.

var RealClock Clock = realClock{}

RealClock is a Clock implementation that uses time.Now().

type Event

type Event struct {
	// The type of operation
	Type EventType

	// The targetted cache
	Cache Cache

	// The entry key (PUT, GET, REMOVE)
	Key interface{}

	// The entry value (PUT) or any value returned by the operation (GET, REMOVE, LEN).
	Value interface{}

	// Any error returned by the operation (PUT, GET, FLUSH).
	Err error
}

Event represents an operation on a cache.

type EventType

type EventType uint8

EventType represents the type of operation that has been performed.

const (
	UNKNOWN EventType = iota
	PUT
	GET
	REMOVE
	FLUSH
	LEN
)

EventType values

func (EventType) GoString

func (e EventType) GoString() string

GoString is fmt.Sprintf("cache.%s", e)

func (EventType) String

func (e EventType) String() string

type EvictionFactory

type EvictionFactory func() EvictionStrategy

type EvictionStrategy

type EvictionStrategy interface {
	// Added indicates an entry have been added to the underlying cache.
	Added(key interface{})

	// Removed indicates an entry have been removed from the underlying cache.
	Removed(key interface{}) (removed bool)

	// Hit indicates an entry has been retrieved to from the underlying cache.
	Hit(key interface{})

	// Pop selects an entry to evict. It returns either its key, or nil if there is no entry to evict.
	Pop() (key interface{})

	fmt.Stringer
}

EvictionStrategy is used to select entries to evict when the underlying cache is full. Most EvictionStrategy are stateful (they track the cached entries) and must not be used by several cache instances.

func NewLFUEviction

func NewLFUEviction() EvictionStrategy

NewLFUEviction creates a new instance of the Least-Frequently-Used strategy.

func NewLRUEviction

func NewLRUEviction() EvictionStrategy

NewLRUEviction creates a new instance of the Least-Recently-Used strategy.

type LoaderFunc

type LoaderFunc func(interface{}) (interface{}, error)

LoaderFunc simulates a cache by calling the functions on call to Get.

type Option

type Option func(Cache) Cache

Option adds optional features new to a cache. Please note the order of options is important: they must be listed from outermost to innermost.

func Emitter

func Emitter(ch chan<- Event) Option

Emitter sends cache events to the given channel.

func Eviction

func Eviction(maxLen int, f EvictionFactory) Option

Eviction adds a layer to evict entries when the underlying cache is full.

func Expiration

func Expiration(ttl time.Duration) Option

Expiration adds automatic expiration to new entries using the given delay.

func ExpirationUsingClock

func ExpirationUsingClock(ttl time.Duration, cl Clock) Option

ExpirationUsingClock adds automatic expiration to new entries using the given clock.

func LFUEviction

func LFUEviction(maxLen int) Option

LFUEviction adds entry eviction using the Least-Frequently-Used strategy

func LRUEviction

func LRUEviction(maxLen int) Option

LRUEviction adds entry eviction using the Least-Recently-Used strategy

func Loader

func Loader(f LoaderFunc) Option

Loader adds a layer to generate values on demand.

func LogErrors

func LogErrors(f Printf) Option

LogErrors catchs and logs errors using the given function.

func Name

func Name(name string) Option

Name gives a name to a cache. This name will be used by Spy(...).

func Spy

func Spy(f Printf) Option

Spy logs operations using the given function.

func Validate

func Validate(f ValidatorFunc) Option

Validate validates every entry using the given function.

func WriteThrough

func WriteThrough(outer Cache) Option

WriteThrough adds a second-level cache. Get operations are tried on "outer" first. If it fails, it tries the inner cache. If it succeed, the value is written to the outer cache. Put and remove operations are forwarded to both caches.

type Printf

type Printf func(string, ...interface{})

Printf is a printf-like function to be used with Spy()

type Validable

type Validable interface {
	IsValid() (bool, error)
}

Validable can validate itself

type ValidatorFunc

type ValidatorFunc func(key, value interface{}) (bool, error)

ValidatorFunc is used to validate cache entries.