cache

Documentation

Overview

Package cache implements a keyed cache for arbitrary values.

Example

package main

import (
	"fmt"

	"github.com/creachadair/mds/cache"
)

func main() {
	c := cache.New(10, cache.LRU[string, int]())
	for i := range 50 {
		c.Put(fmt.Sprint(i+1), i+1)
	}

	fmt.Println("size:", c.Size())

	fmt.Println("has 1:", c.Has("1"))
	fmt.Println("has 40:", c.Has("40"))
	fmt.Println("has 41:", c.Has("41"))
	fmt.Println("has 50:", c.Has("50"))

	fmt.Println(c.Get("41")) // access the value

	c.Put("51", 51)

	fmt.Println("has 42:", c.Has("42")) // gone now
	fmt.Println(c.Get("41"))            // still around

	c.Clear()
	fmt.Println("size:", c.Size())

}

Output:

size: 10
has 1: false
has 40: false
has 41: true
has 50: true
41 true
has 42: false
41 true
size: 0

Index

• func Length[T ~[]byte | ~string](v T) int64
• type Cache
  • func New[K comparable, V any](limit int64, config Config[K, V]) *Cache[K, V]
  • func (c *Cache[K, V]) Clear()
  • func (c *Cache[K, V]) Get(key K) (V, bool)
  • func (c *Cache[K, _]) Has(key K) bool
  • func (c *Cache[K, V]) Len() int
  • func (c *Cache[K, V]) Put(key K, val V) bool
  • func (c *Cache[K, _]) Remove(key K) bool
  • func (c *Cache[K, V]) Size() int64
• type Config
  • func LRU[Key comparable, Value any]() Config[Key, Value]
  • func (c Config[K, V]) OnEvict(f func(K, V)) Config[K, V]
  • func (c Config[K, V]) WithSize(sizeOf func(V) int64) Config[K, V]
  • func (c Config[K, V]) WithStore(s Store[K, V]) Config[K, V]
• type Store

Examples

• Package

Functions

func Length

func Length[T ~[]byte | ~string](v T) int64

Length is a convenience function for using the length of a string or byte slice as its size in a cache. It returns len(v).

Types

type Cache

type Cache[Key comparable, Value any] struct {
	// contains filtered or unexported fields
}

A Cache is a cache mapping keys to values, with a fixed limit on its maximum capacity. Any key may be present in the cache at most once. By default, cache capacity is a number of elements; however, the caller may specify a different size metric using the Config argument to New.

A Cache is safe for concurrent access by multiple goroutines.

func New

func New[K comparable, V any](limit int64, config Config[K, V]) *Cache[K, V]

New constructs a new empty cache with the specified settings. The store and limit fields must be set.

func (*Cache[K, V]) Clear

func (c *Cache[K, V]) Clear()

Clear discards the complete contents of c, leaving it empty.

func (*Cache[K, V]) Get

func (c *Cache[K, V]) Get(key K) (V, bool)

Get reports whether key is present in c, and if so returns the corresponding cached value. This counts as an access of the value for cache accounting.

func (*Cache[K, _]) Has

func (c *Cache[K, _]) Has(key K) bool

Has reports whether a value for key is present in c. This does not count as an access of the value for cache accounting.

func (*Cache[K, V]) Len

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

Len reports the number of items present in the cache.

func (*Cache[K, V]) Put

func (c *Cache[K, V]) Put(key K, val V) bool

Put adds or replaces the value for key in c, and reports whether the value was successfully stored. Put reports false if the cache does not have room to store the provided value; otherwise, the cache is updated and Put reports true. If necessary, items are evicted from the cache to make room for the new value. Which values are evicted is determined by the cache store.

func (*Cache[K, _]) Remove

func (c *Cache[K, _]) Remove(key K) bool

Remove removes the specified key from c, and reports whether a value had been cached for that key.

func (*Cache[K, V]) Size

func (c *Cache[K, V]) Size() int64

Size reports the current size of the items in c.

type Config

type Config[Key comparable, Value any] struct {
	// contains filtered or unexported fields
}

A Config carries the settings for a cache implementation. To set options:

• Use Config.WithStore to set the storage implementation.
• Use Config.WithSize to set the size function.
• Use Config.OnEvict to set the eviction callback.

A zero Config is invalid; at least the store field must be set.

func LRU

func LRU[Key comparable, Value any]() Config[Key, Value]

LRU constructs a Config with a cache store that manages entries with a least-recently used eviction policy.

func (Config[K, V]) OnEvict

func (c Config[K, V]) OnEvict(f func(K, V)) Config[K, V]

OnEvict returns a copy of c with its eviction callback set to f.

If an eviction callback is set, it is called for each entry removed or evicted from the cache.

func (Config[K, V]) WithSize

func (c Config[K, V]) WithSize(sizeOf func(V) int64) Config[K, V]

WithSize returns a copy of c with its size function set to sizeOf.

If no size function is set, the default size of an entry is 1, meaning the limit is based on the number of entries in the cache.

func (Config[K, V]) WithStore

func (c Config[K, V]) WithStore(s Store[K, V]) Config[K, V]

WithStore returns a copy of c with its storage implementation set to s. The storage implementation must be set, or New will panic.

type Store

type Store[Key comparable, Value any] interface {
	// Access reports whether key is present, and if so returns its
	// corresponding value and records an access of the value.
	Access(key Key) (Value, bool)

	// Check reports whether key is present and, if so, returns the
	// corresponding value without recording an access.
	Check(key Key) (Value, bool)

	// Store adds the specified key, value entry to the cache.
	// This counts as an access of the value.
	//
	// If key is already present, Store should panic.
	// That condition should not be possible when used from a Cache.
	Store(key Key, val Value)

	// Remove removes the specified key from the cache.  If key is not present,
	// Remove should do nothing.
	Remove(key Key)

	// Evict evicts an entry from the cache, chosen by the Store, and returns
	// the key and value evicted.
	//
	// If there are no items in the store, it should panic.
	// That condition should not be possible when used from a Cache.
	Evict() (Key, Value)
}

Store is the interface to a cache storage backend. A Store determines the cache eviction policy.

A Cache will serialize access to the methods of Store, so it is not necessary for the implementation to do so separately, unless it is to be shared among multiple cache instances.