Merge pull request #11 from Code-Hex/add/fifo

added FIFO

Author: Code-Hex

README.md

@@ -6,13 +6,21 @@ go-generics-cache is an in-memory key:value store/cache that is suitable for app
 
 - a thread-safe
 - implemented with [Go Generics](https://go.dev/blog/generics-proposal)
-- Simple cache is like `map[string]interface{}` with expiration times
+- TTL supported (with expiration times)
+- Simple cache is like `map[string]interface{}`
   - See [examples](https://github.com/Code-Hex/go-generics-cache/blob/main/simple/example_test.go)
-- LRU cache
-  - See [examples](https://github.com/Code-Hex/go-generics-cache/blob/main/lru/example_test.go)
-- LFU cache
-  - See [examples](https://github.com/Code-Hex/go-generics-cache/blob/main/lfu/example_test.go)
-  - [An O(1) algorithm for implementing the LFU cache eviction scheme](http://dhruvbird.com/lfu.pdf)
+- Cache replacement policies
+  - 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)
+    - 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)
+    - 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)
 
 ## Requirements
 

cache.go

@@ -4,6 +4,7 @@ import (
 	"sync"
 	"time"
 
+	"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/simple"
@@ -21,6 +22,7 @@ var (
 	_ Interface[any, any] = (*simple.Cache[any, any])(nil)
 	_ Interface[any, any] = (*lru.Cache[any, any])(nil)
 	_ Interface[any, any] = (*lfu.Cache[any, any])(nil)
+	_ Interface[any, any] = (*fifo.Cache[any, any])(nil)
 )
 
 // Item is an item
@@ -95,6 +97,13 @@ func AsLFU[K comparable, V any](opts ...lfu.Option) Option[K, V] {
 	}
 }
 
+// AsFIFO is an option to make a new Cache as FIFO algorithm.
+func AsFIFO[K comparable, V any](opts ...fifo.Option) Option[K, V] {
+	return func(o *options[K, V]) {
+		o.cache = fifo.NewCache[K, *Item[K, V]](opts...)
+	}
+}
+
 // New creates a new Cache.
 func New[K comparable, V any](opts ...Option[K, V]) *Cache[K, V] {
 	o := newOptions[K, V]()

example_test.go

@@ -21,7 +21,7 @@ func ExampleCache() {
 }
 
 func ExampleCacheWithExpiration() {
-	c := cache.New(cache.AsLFU[string, int]())
+	c := cache.New(cache.AsFIFO[string, int]())
 	exp := 250 * time.Millisecond
 	c.Set("a", 1, cache.WithExpiration(exp))
 

fifo/example_test.go

@@ -0,0 +1,49 @@
+package fifo_test
+
+import (
+	"fmt"
+
+	"github.com/Code-Hex/go-generics-cache/fifo"
+)
+
+func ExampleCache() {
+	c := fifo.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)
+	c.Delete("a")
+	_, aok2 := c.Get("a")
+	if !aok2 {
+		fmt.Println("key 'a' has been deleted")
+	}
+	// update
+	c.Set("b", 3)
+	newbv, _ := c.Get("b")
+	fmt.Println(newbv)
+	// Output:
+	// 1 true
+	// 2 true
+	// 0 false
+	// key 'a' has been deleted
+	// 3
+}
+
+func ExampleCacheKeys() {
+	c := fifo.NewCache[string, int]()
+	c.Set("foo", 1)
+	c.Set("bar", 2)
+	c.Set("baz", 3)
+	keys := c.Keys()
+	for _, key := range keys {
+		fmt.Println(key)
+	}
+	// Output:
+	// foo
+	// bar
+	// baz
+}

fifo/fifo.go

@@ -0,0 +1,105 @@
+package fifo
+
+import (
+	"container/list"
+)
+
+// Cache is used a FIFO (First in first out) cache replacement policy.
+// In FIFO the item that enter the cache first is evicted first
+// w/o any regard of how often or how many times it was accessed before.
+type Cache[K comparable, V any] struct {
+	items    map[K]*list.Element
+	queue    *list.List // keys
+	capacity int
+}
+
+type entry[K comparable, V any] struct {
+	key K
+	val V
+}
+
+// Option is an option for FIFO 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 cache.
+func NewCache[K comparable, V any](opts ...Option) *Cache[K, V] {
+	o := newOptions()
+	for _, optFunc := range opts {
+		optFunc(o)
+	}
+	return &Cache[K, V]{
+		items:    make(map[K]*list.Element, o.capacity),
+		queue:    list.New(),
+		capacity: o.capacity,
+	}
+}
+
+// Set sets any item to the cache. replacing any existing item.
+func (c *Cache[K, V]) Set(key K, val V) {
+	if c.queue.Len() == c.capacity {
+		e := c.dequeue()
+		delete(c.items, e.Value.(*entry[K, V]).key)
+	}
+	c.Delete(key) // delete old key if already exists specified key.
+	entry := &entry[K, V]{
+		key: key,
+		val: val,
+	}
+	e := c.queue.PushBack(entry)
+	c.items[key] = e
+}
+
+// Get gets an item from the cache.
+// Returns the item or zero value, and a bool indicating whether the key was found.
+func (c *Cache[K, V]) Get(k K) (val V, ok bool) {
+	got, found := c.items[k]
+	if !found {
+		return
+	}
+	return got.Value.(*entry[K, V]).val, true
+}
+
+// Keys returns cache keys.
+func (c *Cache[K, V]) Keys() []K {
+	keys := make([]K, 0, len(c.items))
+	for e := c.queue.Front(); e != nil; e = e.Next() {
+		keys = append(keys, e.Value.(*entry[K, V]).key)
+	}
+	return keys
+}
+
+// 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.queue.Remove(e)
+		delete(c.items, key)
+	}
+}
+
+// Len returns the number of items in the cache.
+func (c *Cache[K, V]) Len() int {
+	return c.queue.Len()
+}
+
+func (c *Cache[K, V]) dequeue() *list.Element {
+	e := c.queue.Front()
+	c.queue.Remove(e)
+	return e
+}

fifo/fifo_test.go

@@ -0,0 +1,88 @@
+package fifo_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/Code-Hex/go-generics-cache/fifo"
+)
+
+func TestSet(t *testing.T) {
+	// set capacity is 1
+	cache := fifo.NewCache[string, int](fifo.WithCapacity(1))
+	cache.Set("foo", 1)
+	if got := cache.Len(); got != 1 {
+		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("bar", 2)
+	if got := cache.Len(); got != 1 {
+		t.Fatalf("invalid length: %d", got)
+	}
+	bar, ok := cache.Get("bar")
+	if bar != 2 || !ok {
+		t.Fatalf("invalid value bar %d, cachehit %v", bar, ok)
+	}
+
+	// checks deleted oldest
+	if _, ok := cache.Get("foo"); ok {
+		t.Fatalf("invalid eviction the oldest value for foo %v", ok)
+	}
+
+	// valid: if over the cap but same key
+	cache.Set("bar", 100)
+	if got := cache.Len(); got != 1 {
+		t.Fatalf("invalid length: %d", got)
+	}
+	bar, ok = cache.Get("bar")
+	if bar != 100 || !ok {
+		t.Fatalf("invalid replacing value bar %d, cachehit %v", bar, ok)
+	}
+}
+
+func TestDelete(t *testing.T) {
+	cache := fifo.NewCache[string, int](fifo.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 := fifo.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{
+		"baz",
+		"bar",
+		"foo",
+	}, ",")
+	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())
+	}
+}