cache

Documentation

Overview

Package cache provides a cache implementation with support for multiple eviction policies.

Currently supported eviction policies:

• LRU (least recently used)
• LFU (least frequently used)
• SLRU (segmented least recently used)
• TinyLFU (tiny least frequently used)

The cache is safe for concurrent access.

Index

• func New[K comparable, V any](capacity int) *builder[K, V]
• func NopEvict[K comparable, V any](K, V)
• type CachePolicy
  • func (e CachePolicy) String() string
• type Clock
• type EvictFunc
• type Interface

Examples

• New

Functions

func New

func New[K comparable, V any](capacity int) *builder[K, V]

New returns a new cache builder with the given capacity. Use the builder to set the eviction policy, eviction callback, and other options. Call Build() to create the cache.

Example

package main

import (
	"fmt"

	"github.com/godaddy/asherah/go/appencryption/pkg/cache"
)

func main() {
	evictionMsg := make(chan string)

	// This callback is executed via a background goroutine whenever an
	// item is evicted from the cache. We use a channel to synchronize
	// the goroutine with this example function so we can verify the
	// item that was evicted.
	evict := func(key int, value string) {
		evictionMsg <- fmt.Sprintln("evicted:", key, value)
	}

	// Create a new LFU cache with a capacity of 3 items and an eviction callback.
	cache := cache.New[int, string](3).LFU().WithEvictFunc(evict).Build()

	// Add some items to the cache.
	cache.Set(1, "foo")
	cache.Set(2, "bar")
	cache.Set(3, "baz")

	// Get an item from the cache.
	value, ok := cache.Get(1)
	if ok {
		fmt.Println("got:", value)
	}

	// Set a new value for an existing key
	cache.Set(2, "two")

	// Add another item to the cache which will evict the least frequently used
	// item (3).
	cache.Set(4, "qux")

	// Print the eviction message sent via the callback above.
	fmt.Print(<-evictionMsg)
}

Output:

got: foo
evicted: 3 baz

func NopEvict

func NopEvict[K comparable, V any](K, V)

NopEvict is a no-op EvictFunc.

Types

type CachePolicy

type CachePolicy string

CachePolicy is an enum for the different eviction policies.

const (
	// LRU is the least recently used cache policy.
	LRU CachePolicy = "lru"
	// LFU is the least frequently used cache policy.
	LFU CachePolicy = "lfu"
	// SLRU is the segmented least recently used cache policy.
	SLRU CachePolicy = "slru"
	// TinyLFU is the tiny least frequently used cache policy.
	TinyLFU CachePolicy = "tinylfu"
)

func (CachePolicy) String

func (e CachePolicy) String() string

String returns the string representation of the eviction policy.

type Clock

type Clock interface {
	Now() time.Time
}

Clock is an interface for getting the current time.

type EvictFunc

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

EvictFunc is called when an item is evicted from the cache. The key and value of the evicted item are passed to the function.

type Interface

type Interface[K comparable, V any] interface {
	Get(key K) (V, bool)
	GetOrPanic(key K) V
	Set(key K, value V)
	Delete(key K) bool
	Len() int
	Capacity() int
	Close() error
}

Interface is intended to be a generic interface for cache implementations.