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
No Locking
package main
import (
"fmt"
"github.com/go-playground/cache/lru"
"time"
)
func main() {
// No guarding
cache := lru.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/lru"
"time"
)
func main() {
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
// ThreadSafe cache with one operation per interaction semantics.
cache := lru.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/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
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 LRU 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 recently 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