lru

README

LRU

This is a Least Recently Used cache backed by a generic doubly linked list with O(1) time complexity.

When to use

You would typically use an LRU cache when:

• Capacity of cache will hold nearly all data.
• Entries being used are being used on a consistent frequency.

Both above will prevent large amounts of data flapping in and out of the cache. If your cache can only hold a fraction of values being stored or data seen on a cadence but high frequency, check out using the LFU cache instead.

Usage

package main

import (
	"context"
	"fmt"
	"github.com/go-playground/cache/lru"
	syncext "github.com/go-playground/pkg/v5/sync"
	"time"
)

func main() {
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	// wrapping with a Mutex, if not needed omit.
	cache := syncext.NewMutex2(lru.New[string, string](100).MaxAge(time.Hour).Build())

	// example of collecting/emitting stats for cache
	// this does require a mutex guard to collect async
	go func(ctx context.Context) {

		var ticker = time.NewTicker(time.Minute)
		defer ticker.Stop()

		for {
			select {
			case <-ctx.Done():
				return
			case <-ticker.C:
				guard := cache.Lock()
				stats := guard.T.Stats()
				guard.Unlock()

				// do things with stats
				fmt.Printf("%#v\n", stats)
			}
		}
	}(ctx)

	guard := cache.Lock()
	guard.T.Set("a", "b")
	guard.T.Set("c", "d")
	option := guard.T.Get("a")
	guard.Unlock()

	if option.IsNone() {
		return
	}
	fmt.Println("result:", option.Unwrap())
}

Documentation

Index

• func New[K comparable, V any](capacity int) *builder[K, V]
• type AutoLockCache
  • func (c AutoLockCache[K, V]) Clear()
  • func (c AutoLockCache[K, V]) Get(key K) (result optionext.Option[V])
  • func (c AutoLockCache[K, V]) Remove(key K)
  • func (c AutoLockCache[K, V]) Set(key K, value V)
  • func (c AutoLockCache[K, V]) Stats() (stats Stats)
• type Cache
  • func (cache *Cache[K, V]) Clear()
  • func (cache *Cache[K, V]) Get(key K) (result optionext.Option[V])
  • func (cache *Cache[K, V]) Remove(key K)
  • func (cache *Cache[K, V]) Set(key K, value V)
  • func (cache *Cache[K, V]) Stats() (stats Stats)
• type Stats

Functions

func New

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

New initializes a builder to create an LRU cache.

Types

type AutoLockCache

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

AutoLockCache is a drop in replacement for Cache which automatically handles locking all cache interactions. This is for ease of use when the flexibility of fine grained locking scemantics are not required.

func (AutoLockCache[K, V]) Clear

func (c AutoLockCache[K, V]) Clear()

Clear empties the cache.

func (AutoLockCache[K, V]) Get

func (c AutoLockCache[K, V]) Get(key K) (result optionext.Option[V])

Get attempts to find an existing cache entry by key. It returns an Option you must check before using the underlying value.

func (AutoLockCache[K, V]) Remove

func (c AutoLockCache[K, V]) Remove(key K)

Remove removes the item matching the provided key from the cache, if not present is a noop.

func (AutoLockCache[K, V]) Set

func (c AutoLockCache[K, V]) Set(key K, value V)

Set sets an item into the cache. It will replace the current entry if there is one.

func (AutoLockCache[K, V]) Stats

func (c AutoLockCache[K, V]) Stats() (stats Stats)

Stats returns the delta of Stats since last call to the Stats function.

type Cache

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

Cache is a configured least recently used cache ready for use.

func (*Cache[K, V]) Clear

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

Clear empties the cache.

func (*Cache[K, V]) Get

func (cache *Cache[K, V]) Get(key K) (result optionext.Option[V])

Get attempts to find an existing cache entry by key. It returns an Option you must check before using the underlying value.

func (*Cache[K, V]) Remove

func (cache *Cache[K, V]) Remove(key K)

Remove removes the item matching the provided key from the cache, if not present is a noop.

func (*Cache[K, V]) Set

func (cache *Cache[K, V]) Set(key K, value V)

Set sets an item into the cache. It will replace the current entry if there is one.

func (*Cache[K, V]) Stats

func (cache *Cache[K, V]) Stats() (stats Stats)

Stats returns the delta of Stats since last call to the Stats function.

type Stats

type Stats struct {
	Capacity, Len                       int
	Hits, Misses, Evictions, Gets, Sets uint
}

Stats represents the cache statistics.