lfu

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 19, 2023 License: Apache-2.0, MIT Imports: 6 Imported by: 0

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

No Locking
package main

import (
	"fmt"
	"github.com/go-playground/cache/lfu"
	"time"
)

func main() {
	// No guarding
	cache := lfu.New[string, string](100).MaxAge(time.Hour).Build()
	cache.Set("a", "b")
	cache.Set("c", "d")
	option := cache.Get("a")

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

	stats := cache.Stats()
	// do things with stats
	fmt.Printf("%#v\n", stats)
}
Auto Locking
package main

import (
	"context"
	"fmt"
	"github.com/go-playground/cache/lfu"
	"time"
)

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

	// ThreadSafe cache with one operation per interaction semantics.
	cache := lfu.New[string, string](100).MaxAge(time.Hour).BuildThreadSafe()

	// example of collecting/emitting stats for cache
	go func(ctx context.Context) {

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

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

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

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

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

	// Have the ability to perform multiple operations at once by grabbing the LockGuard.
	guard := cache.LockGuard()
	guard.T.Set("c", "c")
	guard.T.Set("d", "d")
	guard.T.Remove("a")
	guard.Unlock()
}
Custom Locking
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
	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

Constants

This section is empty.

Variables

This section is empty.

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 added in v0.2.0

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 added in v0.2.0

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

Clear empties the cache.

func (*Cache[K, V]) Get added in v0.2.0

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 added in v0.2.0

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 added in v0.2.0

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 added in v0.8.0

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

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

type Stats added in v0.6.0

type Stats struct {
	// Capacity is the maximum cache capacity.
	Capacity int

	// Len is the current consumed cache capacity.
	Len int

	// Hits is the number of cache hits.
	Hits uint

	// Misses is the number of cache misses.
	Misses uint

	// Evictions is the number of cache evictions performed.
	Evictions uint

	// Gets is the number of cache gets performed regardless of a hit or miss.
	Gets uint

	// Sets is the number of cache sets performed.
	Sets uint
}

Stats represents the cache statistics.

type ThreadSafeCache added in v0.13.0

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

ThreadSafeCache is a drop in replacement for Cache which automatically handles locking all cache interactions. This cache should be used when being used across threads/goroutines.

func (ThreadSafeCache[K, V]) Clear added in v0.13.0

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

Clear empties the cache.

func (ThreadSafeCache[K, V]) Get added in v0.13.0

func (c ThreadSafeCache[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 (ThreadSafeCache[K, V]) LockGuard added in v0.13.0

func (c ThreadSafeCache[K, V]) LockGuard() syncext.MutexGuard[*Cache[K, V], *sync.Mutex]

LockGuard locks the current cache and returns the Guard to Unlock. This is for when you wish to perform multiple operations on the cache during one lock operation.

func (ThreadSafeCache[K, V]) Remove added in v0.13.0

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

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

func (ThreadSafeCache[K, V]) Set added in v0.13.0

func (c ThreadSafeCache[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 (ThreadSafeCache[K, V]) Stats added in v0.13.0

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

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL