cache

Documentation

Overview

Package cache implements Cache similar to hashicorp/golang-lru

Support LRC, LRU and TTL-based eviction. Package is thread-safe and doesn't spawn any goroutines. On every Set() call, cache deletes single oldest entry in case it's expired. In case MaxSize is set, cache deletes the oldest entry disregarding its expiration date to maintain the size, either using LRC or LRU eviction. In case of default TTL (10 years) and default MaxSize (0, unlimited) the cache will be truly unlimited and will never delete entries from itself automatically.

Important: only reliable way of not having expired entries stuck in a cache is to run cache.DeleteExpired periodically using time.Ticker, advisable period is 1/2 of TTL.

Index

• type Cache
  • func NewCache[K comparable, V any]() Cache[K, V]
• type Stats

Examples

• Cache

Types

type Cache

type Cache[K comparable, V any] interface {
	fmt.Stringer

	Add(key K, value V) bool
	Set(key K, value V, ttl time.Duration)
	Get(key K) (V, bool)
	GetExpiration(key K) (time.Time, bool)
	GetOldest() (K, V, bool)
	Contains(key K) (ok bool)
	Peek(key K) (V, bool)
	Values() []V
	Keys() []K
	Len() int
	Remove(key K) bool
	Invalidate(key K)
	InvalidateFn(fn func(key K) bool)
	RemoveOldest() (K, V, bool)
	DeleteExpired()
	Purge()
	Resize(int) int
	Stat() Stats
	// contains filtered or unexported methods
}

Cache defines cache interface

Example

// make cache with short TTL and 3 max keys
cache := NewCache[string, string]().WithMaxKeys(3).WithTTL(time.Millisecond * 10)

// set value under key1.
// with 0 ttl (last parameter) will use cache-wide setting instead (10ms).
cache.Set("key1", "val1", 0)

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

// check for OK value, because otherwise return would be nil and
// type conversion will panic
if ok {
	fmt.Printf("value before expiration is found: %v, value: %q\n", ok, r)
}

time.Sleep(time.Millisecond * 11)

// get value under key1 after key expiration
r, ok = cache.Get("key1")
// don't convert to string as with ok == false value would be nil
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.
// ttl (last parameter) overrides cache-wide ttl.
cache.Set("key2", "val2", time.Minute*5)

fmt.Printf("%+v\n", cache)

Output:

value before expiration is found: true, value: "val1"
value after expiration is found: false, value: "val1"
Size: 1, Stats: {Hits:1 Misses:1 Added:2 Evicted:1} (50.0%)

func NewCache

func NewCache[K comparable, V any]() Cache[K, V]

NewCache returns a new Cache. Default MaxKeys is unlimited (0). Default TTL is 10 years, sane value for expirable cache is 5 minutes. Default eviction mode is LRC, appropriate option allow to change it to LRU.

type Stats

type Stats struct {
	Hits, Misses   int // cache effectiveness
	Added, Evicted int // number of added and evicted records
}

Stats provides statistics for cache