first lfu cache commit

Author: Code-Hex

cache.go

@@ -16,10 +16,17 @@ type Cache[K comparable, V any] interface {
 
 // Item is an item
 type Item[K comparable, V any] struct {
-	Key        K
-	Value      V
-	Expiration time.Duration
-	CreatedAt  time.Time
+	Key            K
+	Value          V
+	ReferenceCount int
+	Expiration     time.Duration
+	CreatedAt      time.Time
+	ReferencedAt   time.Time
+}
+
+func (i *Item[K, V]) Referenced() {
+	i.ReferenceCount++
+	i.ReferencedAt = nowFunc()
 }
 
 var nowFunc = time.Now
@@ -53,11 +60,14 @@ func NewItem[K comparable, V any](key K, val V, opts ...ItemOption) *Item[K, V]
 	for _, optFunc := range opts {
 		optFunc(o)
 	}
+	now := nowFunc()
 	return &Item[K, V]{
-		Key:        key,
-		Value:      val,
-		Expiration: o.expiration,
-		CreatedAt:  nowFunc(),
+		Key:            key,
+		Value:          val,
+		ReferenceCount: 1,
+		Expiration:     o.expiration,
+		CreatedAt:      now,
+		ReferencedAt:   now,
 	}
 }
 

lfu/example_test.go

@@ -0,0 +1,38 @@
+package lfu_test
+
+import (
+	"fmt"
+
+	"github.com/Code-Hex/go-generics-cache/lfu"
+)
+
+func ExampleLFUCache() {
+	c := lfu.NewCache[string, int]()
+	c.Set("a", 1)
+	c.Set("b", 2)
+	av, aok := c.Get("a")
+	bv, bok := c.Get("b")
+	cv, cok := c.Get("c")
+	fmt.Println(av, aok)
+	fmt.Println(bv, bok)
+	fmt.Println(cv, cok)
+	// Output:
+	// 1 true
+	// 2 true
+	// 0 false
+}
+
+func ExampleCacheKeys() {
+	c := lfu.NewCache[string, int]()
+	c.Set("a", 1)
+	c.Set("b", 2)
+	c.Set("c", 3)
+	keys := c.Keys()
+	for _, key := range keys {
+		fmt.Println(key)
+	}
+	// Output:
+	// a
+	// b
+	// c
+}

lfu/lfu.go

@@ -0,0 +1,101 @@
+package lfu
+
+import (
+	"container/heap"
+	"sync"
+
+	cache "github.com/Code-Hex/go-generics-cache"
+)
+
+// Cache is a thread safe LRU cache
+type Cache[K comparable, V any] struct {
+	cap   int
+	queue *priorityQueue[K, V]
+	items map[K]*entry[K, V]
+	mu    sync.RWMutex
+}
+
+var _ cache.Cache[interface{}, any] = (*Cache[interface{}, any])(nil)
+
+// NewCache creates a new LFU cache whose capacity is the default size (128).
+func NewCache[K comparable, V any]() *Cache[K, V] {
+	return NewCacheWithCap[K, V](128)
+}
+
+// NewCacheWithCap creates a new LFU cache whose capacity is the specified size.
+func NewCacheWithCap[K comparable, V any](cap int) *Cache[K, V] {
+	return &Cache[K, V]{
+		cap:   cap,
+		queue: newPriorityQueue[K, V](cap),
+		items: make(map[K]*entry[K, V], cap),
+	}
+}
+
+// Get looks up a key's value from the cache.
+func (c *Cache[K, V]) Get(key K) (zero V, _ bool) {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+
+	e, ok := c.items[key]
+	if !ok {
+		return
+	}
+	if e.item.HasExpired() {
+		return
+	}
+	e.item.Referenced()
+	heap.Fix(c.queue, e.index)
+	return e.item.Value, true
+}
+
+// Set sets a value to the cache with key. replacing any existing value.
+func (c *Cache[K, V]) Set(key K, val V, opts ...cache.ItemOption) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	if e, ok := c.items[key]; ok {
+		c.queue.update(e, val)
+		return
+	}
+
+	e := newEntry(key, val, opts...)
+	heap.Push(c.queue, e)
+	c.items[key] = e
+
+	if len(c.items) > c.cap {
+		evictedEntry := heap.Pop(c.queue).(*entry[K, V])
+		delete(c.items, evictedEntry.item.Key)
+	}
+}
+
+// Keys returns the keys of the cache. the order is from oldest to newest.
+func (c *Cache[K, V]) Keys() []K {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	keys := make([]K, 0, len(c.items))
+	for _, entry := range *c.queue {
+		keys = append(keys, entry.item.Key)
+	}
+	return keys
+}
+
+// Delete deletes the item with provided key from the cache.
+func (c *Cache[K, V]) Delete(key K) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if e, ok := c.items[key]; ok {
+		heap.Remove(c.queue, e.index)
+		delete(c.items, key)
+	}
+}
+
+// Contains reports whether key is within cache.
+func (c *Cache[K, V]) Contains(key K) bool {
+	c.mu.RLock()
+	defer c.mu.RUnlock()
+	e, ok := c.items[key]
+	if !ok {
+		return false
+	}
+	return !e.item.HasExpired()
+}

lfu/priority_queue_test.go

@@ -0,0 +1,75 @@
+package lfu
+
+import (
+	"container/heap"
+	"testing"
+	"time"
+)
+
+func TestPriorityQueue(t *testing.T) {
+	// perl -MList::Util -e 'print join ",", List::Util::shuffle(1..10)'
+	nums := []int{2, 1, 4, 5, 6, 9, 7, 10, 8, 3}
+	queue := newPriorityQueue[int, int](len(nums))
+	entries := make([]*entry[int, int], 0, len(nums))
+
+	for _, v := range nums {
+		entry := newEntry(v, v)
+		entries = append(entries, entry)
+		heap.Push(queue, entry)
+	}
+
+	if got := queue.Len(); len(nums) != got {
+		t.Errorf("want %d, but got %d", len(nums), got)
+	}
+
+	// check the initial state
+	for idx, entry := range *queue {
+		if entry.index != idx {
+			t.Errorf("want index %d, but got %d", entry.index, idx)
+		}
+		if entry.item.ReferenceCount != 1 {
+			t.Errorf("want count 1")
+		}
+		if got := entry.item.Value; nums[idx] != got {
+			t.Errorf("want value %d but got %d", nums[idx], got)
+		}
+	}
+
+	// updates len - 1 entries (updated all reference count and referenced_at)
+	// so the lowest priority will be the last element.
+	//
+	// this loop creates
+	// - Reference counters other than the last element are 2.
+	// - The first element is the oldest referenced_at in reference counter is 2
+	for i := 0; i < len(nums)-1; i++ {
+		entry := entries[i]
+		queue.update(entry, nums[i])
+		time.Sleep(time.Millisecond)
+	}
+
+	// check the priority by reference counter
+	wantValue := nums[len(nums)-1]
+	got := heap.Pop(queue).(*entry[int, int])
+	if got.index != -1 {
+		t.Errorf("want index -1, but got %d", got.index)
+	}
+	if wantValue != got.item.Value {
+		t.Errorf("want the lowest priority value is %d, but got %d", wantValue, got.item.Value)
+	}
+	if want, got := len(nums)-1, queue.Len(); want != got {
+		t.Errorf("want %d, but got %d", want, got)
+	}
+
+	// check the priority by referenced_at
+	wantValue2 := nums[0]
+	got2 := heap.Pop(queue).(*entry[int, int])
+	if got.index != -1 {
+		t.Errorf("want index -1, but got %d", got.index)
+	}
+	if wantValue2 != got2.item.Value {
+		t.Errorf("want the lowest priority value is %d, but got %d", wantValue2, got2.item.Value)
+	}
+	if want, got := len(nums)-2, queue.Len(); want != got {
+		t.Errorf("want %d, but got %d", want, got)
+	}
+}

lfu/priotiry_queue.go

@@ -0,0 +1,66 @@
+package lfu
+
+import (
+	"container/heap"
+
+	cache "github.com/Code-Hex/go-generics-cache"
+)
+
+type entry[K comparable, V any] struct {
+	index int
+	item  *cache.Item[K, V]
+}
+
+func newEntry[K comparable, V any](key K, val V, opts ...cache.ItemOption) *entry[K, V] {
+	return &entry[K, V]{
+		index: 0,
+		item:  cache.NewItem(key, val, opts...),
+	}
+}
+
+type priorityQueue[K comparable, V any] []*entry[K, V]
+
+func newPriorityQueue[K comparable, V any](cap int) *priorityQueue[K, V] {
+	queue := make(priorityQueue[K, V], 0, cap)
+	return &queue
+}
+
+// see example of priority queue: https://pkg.go.dev/container/heap
+var _ heap.Interface = (*priorityQueue[interface{}, interface{}])(nil)
+
+func (l priorityQueue[K, V]) Len() int { return len(l) }
+
+func (l priorityQueue[K, V]) Less(i, j int) bool {
+	if l[i].item.ReferenceCount == l[j].item.ReferenceCount {
+		return l[i].item.ReferencedAt.Before(l[j].item.ReferencedAt)
+	}
+	return l[i].item.ReferenceCount < l[j].item.ReferenceCount
+}
+
+func (l priorityQueue[K, V]) Swap(i, j int) {
+	l[i], l[j] = l[j], l[i]
+	l[i].index = i
+	l[i].index = j
+}
+
+func (l *priorityQueue[K, V]) Push(x interface{}) {
+	entry := x.(*entry[K, V])
+	entry.index = len(*l)
+	*l = append(*l, entry)
+}
+
+func (l *priorityQueue[K, V]) Pop() interface{} {
+	old := *l
+	n := len(old)
+	entry := old[n-1]
+	old[n-1] = nil   // avoid memory leak
+	entry.index = -1 // for safety
+	*l = old[0 : n-1]
+	return entry
+}
+
+func (pq *priorityQueue[K, V]) update(e *entry[K, V], val V) {
+	e.item.Value = val
+	e.item.Referenced()
+	heap.Fix(pq, e.index)
+}