expirable

Documentation

Index

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

Examples

• LRU

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 LRU

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

This is a wrapper around lru[K,V] to make delete-expired routine stop when LRU is garbage collected.

This trick ensures that the deleteExpired goroutine (is running DeleteExpired on lru forever) does not keep the returned LRU object from being garbage collected. When it is garbage collected, the finalizer of LRU stops the deleteExpired goroutine, after which lru can be collected.

Example

// make cache with 10ms TTL and 5 max keys
cache := NewLRU[string, string](5, nil, time.Millisecond*10)

// 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 * 100)

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

func NewLRU[K comparable, V any](size int, onEvict EvictCallback[K, V], ttl time.Duration) *LRU[K, V]

NewLRU 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.

Delete expired entries every 1/100th of ttl value. Goroutine which deletes expired entries runs indefinitely.

func (LRU) Add

func (c LRU) 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 (LRU) Contains

func (c LRU) 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) Get

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

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

func (LRU) GetOldest

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

GetOldest returns the oldest entry

func (LRU) Keys

func (c LRU) Keys() []K

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

func (LRU) Len

func (c LRU) Len() int

Len returns the number of items in the cache.

func (LRU) Peek

func (c LRU) 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) Purge

func (c LRU) Purge()

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

func (LRU) Remove

func (c LRU) Remove(key K) bool

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

func (LRU) RemoveOldest

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

RemoveOldest removes the oldest item from the cache.

func (LRU) Resize

func (c LRU) Resize(size int) (evicted int)

Resize changes the cache size. Size of 0 means unlimited.

func (LRU) Values

func (c LRU) Values() []V

Values returns a slice of the values in the cache, from oldest to newest. Expired entries are filtered out.