lfu

README

LFU

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

When to use

You would typically use an LFU cache when:

• Capacity of cache is far lower than data available.
• Entries being used are high frequency compared to others over time.

Both above will prevent the most frequently use data from flapping in and out of the cache.

Usage

package main

import (
	"context"
	"fmt"
	"github.com/go-playground/cache/lfu"
	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(lfu.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:
				c := cache.Lock()
				stats := c.Stats()
				cache.Unlock()

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

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

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

Documentation

Index

• func New[K comparable, V any](capacity int) *builder[K, V]
• 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 LFU cache.

Types

type Cache

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

Cache is a configured least frequently 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.