simplelru

Documentation

Overview

Package simplelru provides simple LRU implementation based on build-in container/list.

Index

• type EvictCallback
• type ExpirableLRU
  • func NewExpirableLRU[K comparable, V any](size int, onEvict EvictCallback[K, V], ttl, purgeEvery time.Duration) *ExpirableLRU[K, V]
  • func (c *ExpirableLRU[K, V]) Add(key K, value V) (evicted bool)
  • func (c *ExpirableLRU[K, V]) Close()
  • func (c *ExpirableLRU[K, V]) Contains(key K) (ok bool)
  • func (c *ExpirableLRU[K, V]) Get(key K) (value V, ok bool)
  • func (c *ExpirableLRU[K, V]) GetOldest() (key K, value V, ok bool)
  • func (c *ExpirableLRU[K, V]) Keys() []K
  • func (c *ExpirableLRU[K, V]) Len() int
  • func (c *ExpirableLRU[K, V]) Peek(key K) (value V, ok bool)
  • func (c *ExpirableLRU[K, V]) Purge()
  • func (c *ExpirableLRU[K, V]) Remove(key K) bool
  • func (c *ExpirableLRU[K, V]) RemoveOldest() (key K, value V, ok bool)
  • func (c *ExpirableLRU[K, V]) Resize(size int) (evicted int)
• type LRU
  • func NewLRU[K comparable, V any](size int, onEvict EvictCallback[K, V]) (*LRU[K, V], error)
  • func (c *LRU[K, V]) Add(key K, value V) (evicted bool)
  • func (c *LRU[K, V]) Close()
  • func (c *LRU[K, V]) Contains(key K) (ok bool)
  • func (c *LRU[K, V]) Get(key K) (value V, ok bool)
  • func (c *LRU[K, V]) GetOldest() (key K, value V, ok bool)
  • func (c *LRU[K, V]) Keys() []K
  • func (c *LRU[K, V]) Len() int
  • func (c *LRU[K, V]) Peek(key K) (value V, ok bool)
  • func (c *LRU[K, V]) Purge()
  • func (c *LRU[K, V]) Remove(key K) (present bool)
  • func (c *LRU[K, V]) RemoveOldest() (key K, value V, ok bool)
  • func (c *LRU[K, V]) Resize(size int) (evicted int)
• type LRUCache

Examples

• ExpirableLRU

Types

type EvictCallback

type EvictCallback[K comparable, V any] func(key K, value V)

EvictCallback is used to get a callback when a cache entry is evicted

type ExpirableLRU

type ExpirableLRU[K comparable, V any] struct {
	// contains filtered or unexported fields
}

ExpirableLRU implements a thread-safe LRU with expirable entries.

Example

// make cache with 5ms TTL and 3 max keys, purge every 10ms
cache := NewExpirableLRU[string, string](3, nil, time.Millisecond*5, time.Millisecond*10)
// expirable cache need to be closed after used
defer cache.Close()

// set value under key1.
cache.Add("key1", "val1")

// get value under key1
r, ok := cache.Get("key1")

// check for OK value
if ok {
	fmt.Printf("value before expiration is found: %v, value: %q\n", ok, r)
}

// wait for cache to expire
time.Sleep(time.Millisecond * 16)

// get value under key1 after key expiration
r, ok = cache.Get("key1")
fmt.Printf("value after expiration is found: %v, value: %q\n", ok, r)

// set value under key2, would evict old entry because it is already expired.
cache.Add("key2", "val2")

fmt.Printf("Cache len: %d\n", cache.Len())

Output:

value before expiration is found: true, value: "val1"
value after expiration is found: false, value: ""
Cache len: 1

func NewExpirableLRU

func NewExpirableLRU[K comparable, V any](size int, onEvict EvictCallback[K, V], ttl, purgeEvery time.Duration) *ExpirableLRU[K, V]

NewExpirableLRU returns a new thread-safe cache with expirable entries.

Size parameter set to 0 makes cache of unlimited size, e.g. turns LRU mechanism off.

Providing 0 TTL turns expiring off.

Activates deleteExpired by purgeEvery duration. If MaxKeys and TTL are defined and PurgeEvery is zero, PurgeEvery will be set to 5 minutes.

func (*ExpirableLRU[K, V]) Add

func (c *ExpirableLRU[K, V]) Add(key K, value V) (evicted bool)

Add adds a value to the cache. Returns true if an eviction occurred. Returns false if there was no eviction: the item was already in the cache, or the size was not exceeded.

func (*ExpirableLRU[K, V]) Close

func (c *ExpirableLRU[K, V]) Close()

Close cleans the cache and destroys running goroutines

func (*ExpirableLRU[K, V]) Contains

func (c *ExpirableLRU[K, V]) Contains(key K) (ok bool)

Contains checks if a key is in the cache, without updating the recent-ness or deleting it for being stale.

func (*ExpirableLRU[K, V]) Get

func (c *ExpirableLRU[K, V]) Get(key K) (value V, ok bool)

Get looks up a key's value from the cache.

func (*ExpirableLRU[K, V]) GetOldest

func (c *ExpirableLRU[K, V]) GetOldest() (key K, value V, ok bool)

GetOldest returns the oldest entry

func (*ExpirableLRU[K, V]) Keys

func (c *ExpirableLRU[K, V]) Keys() []K

Keys returns a slice of the keys in the cache, from oldest to newest.

func (*ExpirableLRU[K, V]) Len

func (c *ExpirableLRU[K, V]) Len() int

Len returns the number of items in the cache.

func (*ExpirableLRU[K, V]) Peek

func (c *ExpirableLRU[K, V]) Peek(key K) (value V, ok bool)

Peek returns the key value (or undefined if not found) without updating the "recently used"-ness of the key.

func (*ExpirableLRU[K, V]) Purge

func (c *ExpirableLRU[K, V]) Purge()

Purge clears the cache completely. onEvict is called for each evicted key.

func (*ExpirableLRU[K, V]) Remove

func (c *ExpirableLRU[K, V]) Remove(key K) bool

Remove removes the provided key from the cache, returning if the key was contained.

func (*ExpirableLRU[K, V]) RemoveOldest

func (c *ExpirableLRU[K, V]) RemoveOldest() (key K, value V, ok bool)

RemoveOldest removes the oldest item from the cache.

func (*ExpirableLRU[K, V]) Resize

func (c *ExpirableLRU[K, V]) Resize(size int) (evicted int)

Resize changes the cache size. Size of 0 doesn't resize the cache, as it means unlimited.

type LRU

type LRU[K comparable, V any] struct {
	// contains filtered or unexported fields
}

LRU implements a non-thread safe fixed size LRU cache

func NewLRU

func NewLRU[K comparable, V any](size int, onEvict EvictCallback[K, V]) (*LRU[K, V], error)

NewLRU constructs an LRU of the given size

func (*LRU[K, V]) Add

func (c *LRU[K, V]) Add(key K, value V) (evicted bool)

Add adds a value to the cache. Returns true if an eviction occurred.

func (*LRU[K, V]) Close

func (c *LRU[K, V]) Close()

Close does nothing for this type of cache.

func (*LRU[K, V]) Contains

func (c *LRU[K, V]) Contains(key K) (ok bool)

Contains checks if a key is in the cache, without updating the recent-ness or deleting it for being stale.

func (*LRU[K, V]) Get

func (c *LRU[K, V]) Get(key K) (value V, ok bool)

Get looks up a key's value from the cache.

func (*LRU[K, V]) GetOldest

func (c *LRU[K, V]) GetOldest() (key K, value V, ok bool)

GetOldest returns the oldest entry

func (*LRU[K, V]) Keys

func (c *LRU[K, V]) Keys() []K

Keys returns a slice of the keys in the cache, from oldest to newest.

func (*LRU[K, V]) Len

func (c *LRU[K, V]) Len() int

Len returns the number of items in the cache.

func (*LRU[K, V]) Peek

func (c *LRU[K, V]) Peek(key K) (value V, ok bool)

Peek returns the key value (or undefined if not found) without updating the "recently used"-ness of the key.

func (*LRU[K, V]) Purge

func (c *LRU[K, V]) Purge()

Purge is used to completely clear the cache.

func (*LRU[K, V]) Remove

func (c *LRU[K, V]) Remove(key K) (present bool)

Remove removes the provided key from the cache, returning if the key was contained.

func (*LRU[K, V]) RemoveOldest

func (c *LRU[K, V]) RemoveOldest() (key K, value V, ok bool)

RemoveOldest removes the oldest item from the cache.

func (*LRU[K, V]) Resize

func (c *LRU[K, V]) Resize(size int) (evicted int)

Resize changes the cache size.

type LRUCache

type LRUCache[K comparable, V any] interface {
	// Adds a value to the cache, returns true if an eviction occurred and
	// updates the "recently used"-ness of the key.
	Add(key K, value V) bool

	// Returns key's value from the cache and
	// updates the "recently used"-ness of the key. #value, isFound
	Get(key K) (value V, ok bool)

	// Checks if a key exists in cache without updating the recent-ness.
	Contains(key K) (ok bool)

	// Returns key's value without updating the "recently used"-ness of the key.
	Peek(key K) (value V, ok bool)

	// Removes a key from the cache.
	Remove(key K) bool

	// Removes the oldest entry from cache.
	RemoveOldest() (K, V, bool)

	// Returns the oldest entry from the cache. #key, value, isFound
	GetOldest() (K, V, bool)

	// Returns a slice of the keys in the cache, from oldest to newest.
	Keys() []K

	// Returns the number of items in the cache.
	Len() int

	// Clears all cache entries.
	Purge()

	// Resizes cache, returning number evicted
	Resize(int) int
}

LRUCache is the interface for simple LRU cache.