Merge pull request #13 from Code-Hex/add/mru

added MRU

Author: Code-Hex

README.md

@@ -10,17 +10,20 @@ go-generics-cache is an in-memory key:value store/cache that is suitable for app
 - Simple cache is like `map[string]interface{}`
   - See [examples](https://github.com/Code-Hex/go-generics-cache/blob/main/simple/example_test.go)
 - Cache replacement policies
-  - Least recently used (LRU)
+  - **Least recently used (LRU)**
     - Discards the least recently used items first.
     - See [examples](https://github.com/Code-Hex/go-generics-cache/blob/main/lru/example_test.go)
-  - Least-frequently used (LFU)
+  - **Least-frequently used (LFU)**
     - Counts how often an item is needed. Those that are used least often are discarded first.
     - [An O(1) algorithm for implementing the LFU cache eviction scheme](http://dhruvbird.com/lfu.pdf)
     - See [examples](https://github.com/Code-Hex/go-generics-cache/blob/main/lfu/example_test.go)
-  - First in first out (FIFO)
+  - **First in first out (FIFO)**
     - Using this algorithm the cache behaves in the same way as a [FIFO queue](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)).
     - The cache evicts the blocks in the order they were added, without any regard to how often or how many times they were accessed before.
 	- See [examples](https://github.com/Code-Hex/go-generics-cache/blob/main/fifo/example_test.go)
+  - **Most recently used (MRU)**
+    - In contrast to Least Recently Used (LRU), MRU discards the most recently used items first.
+	- See [examples](https://github.com/Code-Hex/go-generics-cache/blob/main/mru/example_test.go)
 
 ## Requirements
 
@@ -41,7 +44,7 @@ go version devel go1.18-c2397905e0 Sat Nov 13 03:33:55 2021 +0000 darwin/arm64
 
 ## Usage
 
-See also [examples](https://github.com/Code-Hex/go-generics-cache/blob/main/example_test.go)
+See also [examples](https://github.com/Code-Hex/go-generics-cache/blob/main/example_test.go) or [gotipplay playground](https://gotipplay.golang.org/p/MRF_I4oUS_W)
 
 ```go
 package main

cache.go

@@ -7,6 +7,7 @@ import (
 	"github.com/Code-Hex/go-generics-cache/fifo"
 	"github.com/Code-Hex/go-generics-cache/lfu"
 	"github.com/Code-Hex/go-generics-cache/lru"
+	"github.com/Code-Hex/go-generics-cache/mru"
 	"github.com/Code-Hex/go-generics-cache/simple"
 )
 
@@ -23,6 +24,7 @@ var (
 	_ Interface[any, any] = (*lru.Cache[any, any])(nil)
 	_ Interface[any, any] = (*lfu.Cache[any, any])(nil)
 	_ Interface[any, any] = (*fifo.Cache[any, any])(nil)
+	_ Interface[any, any] = (*mru.Cache[any, any])(nil)
 )
 
 // Item is an item
@@ -104,6 +106,13 @@ func AsFIFO[K comparable, V any](opts ...fifo.Option) Option[K, V] {
 	}
 }
 
+// AsMRU is an option to make a new Cache as MRU algorithm.
+func AsMRU[K comparable, V any](opts ...mru.Option) Option[K, V] {
+	return func(o *options[K, V]) {
+		o.cache = mru.NewCache[K, *Item[K, V]](opts...)
+	}
+}
+
 // New creates a new thread safe Cache.
 //
 // There are several Cache replacement policies available with you specified any options.

example_test.go

@@ -46,7 +46,7 @@ func ExampleCacheWithExpiration() {
 }
 
 func ExampleDelete() {
-	c := cache.New(cache.AsLRU[string, int]())
+	c := cache.New(cache.AsMRU[string, int]())
 	c.Set("a", 1)
 	c.Delete("a")
 	gota, aok := c.Get("a")

lru/lru.go

@@ -20,7 +20,7 @@ type entry[K comparable, V any] struct {
 	val V
 }
 
-// Option is an option for LFU cache.
+// Option is an option for LRU cache.
 type Option func(*options)
 
 type options struct {

mru/example_test.go

@@ -0,0 +1,38 @@
+package mru_test
+
+import (
+	"fmt"
+
+	"github.com/Code-Hex/go-generics-cache/mru"
+)
+
+func ExampleMRUCache() {
+	c := mru.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 := mru.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:
+	// c
+	// b
+	// a
+}

mru/mru.go

@@ -0,0 +1,118 @@
+package mru
+
+import (
+	"container/list"
+)
+
+// Cache is used a MRU (Most recently used) cache replacement policy.
+//
+// In contrast to Least Recently Used (LRU), MRU discards the most recently used items first.
+type Cache[K comparable, V any] struct {
+	cap   int
+	list  *list.List
+	items map[K]*list.Element
+}
+
+type entry[K comparable, V any] struct {
+	key K
+	val V
+}
+
+// Option is an option for MRU cache.
+type Option func(*options)
+
+type options struct {
+	capacity int
+}
+
+func newOptions() *options {
+	return &options{
+		capacity: 128,
+	}
+}
+
+// WithCapacity is an option to set cache capacity.
+func WithCapacity(cap int) Option {
+	return func(o *options) {
+		o.capacity = cap
+	}
+}
+
+// NewCache creates a new non-thread safe MRU cache whose capacity is the default size (128).
+func NewCache[K comparable, V any](opts ...Option) *Cache[K, V] {
+	o := newOptions()
+	for _, optFunc := range opts {
+		optFunc(o)
+	}
+	return &Cache[K, V]{
+		cap:   o.capacity,
+		list:  list.New(),
+		items: make(map[K]*list.Element, o.capacity),
+	}
+}
+
+// Get looks up a key's value from the cache.
+func (c *Cache[K, V]) Get(key K) (zero V, _ bool) {
+	e, ok := c.items[key]
+	if !ok {
+		return
+	}
+	// updates cache order
+	c.list.MoveToBack(e)
+	return e.Value.(*entry[K, V]).val, true
+}
+
+// Set sets a value to the cache with key. replacing any existing value.
+func (c *Cache[K, V]) Set(key K, val V) {
+	if e, ok := c.items[key]; ok {
+		// updates cache order
+		c.list.MoveToBack(e)
+		entry := e.Value.(*entry[K, V])
+		entry.val = val
+		return
+	}
+
+	if c.list.Len() == c.cap {
+		c.deleteNewest()
+	}
+
+	newEntry := &entry[K, V]{
+		key: key,
+		val: val,
+	}
+	e := c.list.PushBack(newEntry)
+	c.items[key] = e
+}
+
+// Keys returns the keys of the cache. the order is from recently used.
+func (c *Cache[K, V]) Keys() []K {
+	keys := make([]K, 0, len(c.items))
+	for ent := c.list.Back(); ent != nil; ent = ent.Prev() {
+		entry := ent.Value.(*entry[K, V])
+		keys = append(keys, entry.key)
+	}
+	return keys
+}
+
+// Len returns the number of items in the cache.
+func (c *Cache[K, V]) Len() int {
+	return c.list.Len()
+}
+
+// Delete deletes the item with provided key from the cache.
+func (c *Cache[K, V]) Delete(key K) {
+	if e, ok := c.items[key]; ok {
+		c.delete(e)
+	}
+}
+
+func (c *Cache[K, V]) deleteNewest() {
+	e := c.list.Front()
+	c.delete(e)
+}
+
+func (c *Cache[K, V]) delete(e *list.Element) {
+	c.list.Remove(e)
+	entry := e.Value.(*entry[K, V])
+	delete(c.items, entry.key)
+}

mru/mru_test.go

@@ -0,0 +1,93 @@
+package mru_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/Code-Hex/go-generics-cache/mru"
+)
+
+func TestSet(t *testing.T) {
+	cache := mru.NewCache[string, int](mru.WithCapacity(2))
+	cache.Set("foo", 1)
+	cache.Set("bar", 2)
+	if got := cache.Len(); got != 2 {
+		t.Fatalf("invalid length: %d", got)
+	}
+	if got, ok := cache.Get("foo"); got != 1 || !ok {
+		t.Fatalf("invalid value got %d, cachehit %v", got, ok)
+	}
+
+	// if over the cap
+	cache.Set("baz", 3)
+	if got := cache.Len(); got != 2 {
+		t.Fatalf("invalid length: %d", got)
+	}
+	baz, ok := cache.Get("baz")
+	if baz != 3 || !ok {
+		t.Fatalf("invalid value baz %d, cachehit %v", baz, ok)
+	}
+
+	// check eviction most recently used
+	if _, ok := cache.Get("bar"); ok {
+		t.Log(cache.Keys())
+		t.Fatalf("invalid eviction the newest value for bar %v", ok)
+	}
+
+	// current state
+	// - baz <- recently used
+	// - foo
+
+	// valid: if over the cap but specify the oldest key
+	cache.Set("foo", 100)
+	if got := cache.Len(); got != 2 {
+		t.Fatalf("invalid length: %d", got)
+	}
+	foo, ok := cache.Get("foo")
+	if foo != 100 || !ok {
+		t.Fatalf("invalid replacing value foo %d, cachehit %v", foo, ok)
+	}
+}
+
+func TestDelete(t *testing.T) {
+	cache := mru.NewCache[string, int](mru.WithCapacity(1))
+	cache.Set("foo", 1)
+	if got := cache.Len(); got != 1 {
+		t.Fatalf("invalid length: %d", got)
+	}
+
+	cache.Delete("foo2")
+	if got := cache.Len(); got != 1 {
+		t.Fatalf("invalid length after deleted does not exist key: %d", got)
+	}
+
+	cache.Delete("foo")
+	if got := cache.Len(); got != 0 {
+		t.Fatalf("invalid length after deleted: %d", got)
+	}
+	if _, ok := cache.Get("foo"); ok {
+		t.Fatalf("invalid get after deleted %v", ok)
+	}
+}
+
+func TestKeys(t *testing.T) {
+	cache := mru.NewCache[string, int]()
+	cache.Set("foo", 1)
+	cache.Set("bar", 2)
+	cache.Set("baz", 3)
+	cache.Set("bar", 4) // again
+	cache.Set("foo", 5) // again
+
+	got := strings.Join(cache.Keys(), ",")
+	want := strings.Join([]string{
+		"foo",
+		"bar",
+		"baz",
+	}, ",")
+	if got != want {
+		t.Errorf("want %q, but got %q", want, got)
+	}
+	if len(cache.Keys()) != cache.Len() {
+		t.Errorf("want number of keys %d, but got %d", len(cache.Keys()), cache.Len())
+	}
+}