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 ¶
- func New[K comparable, V any](capacity int) *builder[K, V]
- type Cache
- type Stats
- type ThreadSafeCache
- func (c ThreadSafeCache[K, V]) Clear()
- func (c ThreadSafeCache[K, V]) Get(key K) (result optionext.Option[V])
- func (c ThreadSafeCache[K, V]) LockGuard() syncext.MutexGuard[*Cache[K, V], *sync.Mutex]
- func (c ThreadSafeCache[K, V]) Remove(key K)
- func (c ThreadSafeCache[K, V]) Set(key K, value V)
- func (c ThreadSafeCache[K, V]) Stats() (stats Stats)
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
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.
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.
Source Files