cache

Documentation

Index

• Variables
• type Cache
  • func NewLRU(opts LRUOptions) Cache
  • func NewLRUStriped(opts LRUOptions) (Cache, error)
• type CacheOptions
• type LRU
  • func (l *LRU) Get(key string, value interface{}) error
  • func (l *LRU) GetInvalidateClusterEvent() string
  • func (l *LRU) Keys() ([]string, error)
  • func (l *LRU) Len() (int, error)
  • func (l *LRU) Name() string
  • func (l *LRU) Purge() error
  • func (l *LRU) Remove(key string) error
  • func (l *LRU) Set(key string, value interface{}) error
  • func (l *LRU) SetWithDefaultExpiry(key string, value interface{}) error
  • func (l *LRU) SetWithExpiry(key string, value interface{}, ttl time.Duration) error
• type LRUOptions
• type LRUStriped
  • func (L LRUStriped) Get(key string, value interface{}) error
  • func (L LRUStriped) GetInvalidateClusterEvent() string
  • func (L LRUStriped) Keys() ([]string, error)
  • func (L LRUStriped) Len() (int, error)
  • func (L LRUStriped) Name() string
  • func (L LRUStriped) Purge() error
  • func (L LRUStriped) Remove(key string) error
  • func (L LRUStriped) Set(key string, value interface{}) error
  • func (L LRUStriped) SetWithDefaultExpiry(key string, value interface{}) error
  • func (L LRUStriped) SetWithExpiry(key string, value interface{}, ttl time.Duration) error
• type Provider
  • func NewProvider() Provider

Variables

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

ErrKeyNotFound is the error when the given key is not found

Types

type Cache

type Cache interface {
	// Purge is used to completely clear the cache.
	Purge() error

	// Set adds the given key and value to the store without an expiry. If the key already exists,
	// it will overwrite the previous value.
	Set(key string, value interface{}) error

	// SetWithDefaultExpiry adds the given key and value to the store with the default expiry. If
	// the key already exists, it will overwrite the previoous value
	SetWithDefaultExpiry(key string, value interface{}) error

	// SetWithExpiry adds the given key and value to the cache with the given expiry. If the key
	// already exists, it will overwrite the previoous value
	SetWithExpiry(key string, value interface{}, ttl time.Duration) error

	// Get the content stored in the cache for the given key, and decode it into the value interface.
	// Return ErrKeyNotFound if the key is missing from the cache
	Get(key string, value interface{}) error

	// Remove deletes the value for a given key.
	Remove(key string) error

	// Keys returns a slice of the keys in the cache.
	Keys() ([]string, error)

	// Len returns the number of items in the cache.
	Len() (int, error)

	// GetInvalidateClusterEvent returns the cluster event configured when this cache was created.
	GetInvalidateClusterEvent() string

	// Name returns the name of the cache
	Name() string
}

Cache is a representation of a cache store that aims to replace cache.Cache

func NewLRU

func NewLRU(opts LRUOptions) Cache

NewLRU creates an LRU of the given size.

func NewLRUStriped

func NewLRUStriped(opts LRUOptions) (Cache, error)

NewLRUStriped creates a striped LRU cache using the special LRUOptions.StripedBuckets value. See LRUStriped and LRUOptions for more details.

Not that in order to prevent false eviction, this LRU cache adds 10% (computation is rounded up) of the requested size to the total cache size.

type CacheOptions

type CacheOptions struct {
	Size                   int
	DefaultExpiry          time.Duration
	Name                   string
	InvalidateClusterEvent string
	Striped                bool
	StripedBuckets         int
}

CacheOptions contains options for initializaing a cache

type LRU

type LRU struct {
	// contains filtered or unexported fields
}

LRU is a thread-safe fixed size LRU cache.

func (*LRU) Get

func (l *LRU) Get(key string, value interface{}) error

Get the content stored in the cache for the given key, and decode it into the value interface. return ErrKeyNotFound if the key is missing from the cache

func (*LRU) GetInvalidateClusterEvent

func (l *LRU) GetInvalidateClusterEvent() string

GetInvalidateClusterEvent returns the cluster event configured when this cache was created.

func (*LRU) Keys

func (l *LRU) Keys() ([]string, error)

Keys returns a slice of the keys in the cache.

func (*LRU) Len

func (l *LRU) Len() (int, error)

Len returns the number of items in the cache.

func (*LRU) Name

func (l *LRU) Name() string

Name returns the name of the cache

func (*LRU) Purge

func (l *LRU) Purge() error

Purge is used to completely clear the cache.

func (*LRU) Remove

func (l *LRU) Remove(key string) error

Remove deletes the value for a key.

func (*LRU) Set

func (l *LRU) Set(key string, value interface{}) error

Set adds the given key and value to the store without an expiry. If the key already exists, it will overwrite the previous value.

func (*LRU) SetWithDefaultExpiry

func (l *LRU) SetWithDefaultExpiry(key string, value interface{}) error

SetWithDefaultExpiry adds the given key and value to the store with the default expiry. If the key already exists, it will overwrite the previoous value

func (*LRU) SetWithExpiry

func (l *LRU) SetWithExpiry(key string, value interface{}, ttl time.Duration) error

SetWithExpiry adds the given key and value to the cache with the given expiry. If the key already exists, it will overwrite the previoous value

type LRUOptions

type LRUOptions struct {
	Name                   string
	Size                   int
	DefaultExpiry          time.Duration
	InvalidateClusterEvent string
	// StripedBuckets is used only by LRUStriped and shouldn't be greater than the number
	// of CPUs available on the machine running this cache.
	StripedBuckets int
}

LRUOptions contains options for initializing LRU cache

type LRUStriped

type LRUStriped struct {
	// contains filtered or unexported fields
}

LRUStriped keeps LRU caches in buckets in order to lower mutex contention. This is achieved by hashing the input key to map it to a dedicated bucket. Each bucket (an LRU cache) has its own lock that helps distributing the lock contention on multiple threads/cores, leading to less wait times.

LRUStriped implements the Cache interface with the same behavior as LRU.

Note that, because of it's distributed nature, the fixed size cannot be strictly respected and you may have a tiny bit more space for keys than you defined through LRUOptions. Bucket size is computed as follows: (size / nbuckets) + (size % nbuckets)

Because of this size limit per bucket, and because of the nature of the data, you may have buckets filled unevenly, and because of this, keys will be evicted from the entire cache where a simple LRU wouldn't have. Example:

Two buckets B1 and B2, of max size 2 each, meaning, theoretically, a max size of 4:

• Say you have a set of 3 keys, they could fill an entire LRU cache.
• But if all those keys are assigned to a single bucket B1, the first key will be evicted from B1
• B2 will remain empty, even though there was enough memory allocated

With 4 buckets and random UUIDs as keys, the amount of false evictions is around 5%.

By default, the number of buckets equals the number of cpus returned from runtime.NumCPU.

This struct is lock-free and intended to be used without lock.

func (LRUStriped) Get

func (L LRUStriped) Get(key string, value interface{}) error

Get does the same as LRU.Get

func (LRUStriped) GetInvalidateClusterEvent

func (L LRUStriped) GetInvalidateClusterEvent() string

GetInvalidateClusterEvent does the same as LRU.GetInvalidateClusterEvent

func (LRUStriped) Keys

func (L LRUStriped) Keys() ([]string, error)

Keys does the same as LRU.Keys. However, because this is lock-free, keys might be inserted or removed from a previously scanned LRU cache. This is not as precise as using a single LRU instance.

func (LRUStriped) Len

func (L LRUStriped) Len() (int, error)

Len does the same as LRU.Len. As for LRUStriped.Keys, this call cannot be precise.

func (LRUStriped) Name

func (L LRUStriped) Name() string

Name does the same as LRU.Name

func (LRUStriped) Purge

func (L LRUStriped) Purge() error

Purge loops through each LRU cache for purging. Since LRUStriped doesn't use any lock, each LRU bucket is purged after another one, which means that keys could still be present after a call to Purge.

func (LRUStriped) Remove

func (L LRUStriped) Remove(key string) error

Remove does the same as LRU.Remove

func (LRUStriped) Set

func (L LRUStriped) Set(key string, value interface{}) error

Set does the same as LRU.Set

func (LRUStriped) SetWithDefaultExpiry

func (L LRUStriped) SetWithDefaultExpiry(key string, value interface{}) error

SetWithDefaultExpiry does the same as LRU.SetWithDefaultExpiry

func (LRUStriped) SetWithExpiry

func (L LRUStriped) SetWithExpiry(key string, value interface{}, ttl time.Duration) error

SetWithExpiry does the same as LRU.SetWithExpiry

type Provider

type Provider interface {
	// NewCache creates a new cache with given options.
	NewCache(opts *CacheOptions) (Cache, error)
	// Connect opens a new connection to the cache using specific provider parameters.
	Connect() error
	// Close releases any resources used by the cache provider.
	Close() error
}

Provider is a provider for Cache

func NewProvider

func NewProvider() Provider

NewProvider creates a new CacheProvider