lru

Documentation

Overview

Package lru provides least-recently-used (LRU) cache.

Package lru provides least-recently-used (LRU) cache.

Index

• type Cache
  • func New(size int) *Cache
  • func NewWithoutLock(size int) *Cache
  • func (c *Cache) Get(key interface{}) interface{}
  • func (c *Cache) Len() int
  • func (c *Cache) Mutate(key interface{}, gen func(interface{}) interface{}) (value interface{})
  • func (c *Cache) Peek(key interface{}) interface{}
  • func (c *Cache) Purge()
  • func (c *Cache) Put(key, value interface{}) (existed bool)
  • func (c *Cache) Remove(key interface{}) interface{}
• type Config
  • func (cfg Config) New() *Cache
• type Heuristic
• type Locker

Types

type Cache

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

Cache is a goroutine-safe least-recently-used (LRU) cache implementation. The cache stores key-value mapping entries up to a size limit. If more items are added past that limit, the entries that have have been referenced least recently will be evicted.

This cache uses a read-write mutex, allowing multiple simultaneous non-mutating readers (Peek), but only one mutating reader/writer (Get, Put, Mutate).

func New

func New(size int) *Cache

New creates a new goroutine-safe Cache instance retains a maximum number of elements.

func NewWithoutLock

func NewWithoutLock(size int) *Cache

NewWithoutLock creates a new Cache instance retains a maximum number of elements. This instance does not perform any locking, and therefore is not goroutine-safe.

func (*Cache) Get

func (c *Cache) Get(key interface{}) interface{}

Get fetches the element associated with the supplied key, updating its recently-used standing.

Get uses the cache Locker's read/write lock.

func (*Cache) Len

func (c *Cache) Len() int

Len returns the number of entries in the cache.

Len uses the cache Locker's read lock.

func (*Cache) Mutate

func (c *Cache) Mutate(key interface{}, gen func(interface{}) interface{}) (value interface{})

Mutate adds a value to the cache, using a generator to create the value.

Mutate uses the cache Locker's read/write lock.

The generator will receive the current value, or nil if there is no current value. It returns the new value, or nil to remove this key from the cache.

The generator is called while the cache's lock is held. This means that the generator MUST NOT call any cache methods during its execution, as doing so will result in deadlock/panic.

Returns the value that was put in the cache, which is the value returned by the generator.

The key will be considered most recently used regardless of whether it was put.

func (*Cache) Peek

func (c *Cache) Peek(key interface{}) interface{}

Peek fetches the element associated with the supplied key without updating the element's recently-used standing.

Peek uses the cache Locker's read lock.

func (*Cache) Purge

func (c *Cache) Purge()

Purge clears the full contents of the cache.

Purge uses the cache Locker's read/write lock.

func (*Cache) Put

func (c *Cache) Put(key, value interface{}) (existed bool)

Put adds a new value to the cache. The value in the cache will be replaced regardless of whether an item with the same key already existed.

Put uses the cache Locker's read/write lock.

Returns whether not a value already existed for the key.

The new item will be considered most recently used.

func (*Cache) Remove

func (c *Cache) Remove(key interface{}) interface{}

Remove removes an entry from the cache. If the key is present, its current value will be returned; otherwise, nil will be returned.

Remove uses the cache Locker's read/write lock.

type Config

type Config struct {
	// Locker is the read/write Locker implementation to use for this cache. If
	// nil, the cache will not lock around operations and will not be
	// goroutine-safe.
	Locker Locker

	// Heuristic is the LRU heuristic to use.
	//
	// If nil, the cache will never prune elements.
	Heuristic Heuristic
}

Config is a configuration structure for the cache.

func (Config) New

func (cfg Config) New() *Cache

New instantiates a new cache from the current configuration.

type Heuristic

type Heuristic func(int, interface{}) bool

Heuristic is a callback function that is run after every LRU mutation to determine how many elements (if any) to drop. It is invoked with the current number of elements in the cache and the least-recently-used item.

Heuristic will be called repeatedly until it returns true, indicating that the cache is sufficiently pruned. Every time it returns false, the least-recently-used element in the cache will be evicted.

Heuristic is called while the cache holds its write lock, meaning that no locking cache methods may be called during this callback.

type Locker

type Locker interface {
	sync.Locker

	// RLock locks the Locker for reading.
	RLock()
	// RLock unlocks the Locker for reading.
	RUnlock()
}

Locker is a read/write locker interface.

Its RLock and RUnlock methods follow the same conventions as sync.RWMutex.