Merge pull request #14 from Code-Hex/add/clock

Add clock

Author: Code-Hex

README.md

@@ -24,6 +24,9 @@ go-generics-cache is an in-memory key:value store/cache that is suitable for app
   - **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)
+  - **Clock**
+    - Clock is a more efficient version of FIFO than Second-chance cache algorithm.
+	- See [examples](https://github.com/Code-Hex/go-generics-cache/blob/main/clock/example_test.go)
 
 ## Requirements
 

cache.go

@@ -4,6 +4,7 @@ import (
 	"sync"
 	"time"
 
+	"github.com/Code-Hex/go-generics-cache/clock"
 	"github.com/Code-Hex/go-generics-cache/fifo"
 	"github.com/Code-Hex/go-generics-cache/lfu"
 	"github.com/Code-Hex/go-generics-cache/lru"
@@ -25,6 +26,7 @@ var (
 	_ Interface[any, any] = (*lfu.Cache[any, any])(nil)
 	_ Interface[any, any] = (*fifo.Cache[any, any])(nil)
 	_ Interface[any, any] = (*mru.Cache[any, any])(nil)
+	_ Interface[any, any] = (*clock.Cache[any, any])(nil)
 )
 
 // Item is an item
@@ -113,6 +115,13 @@ func AsMRU[K comparable, V any](opts ...mru.Option) Option[K, V] {
 	}
 }
 
+// AsClock is an option to make a new Cache as clock algorithm.
+func AsClock[K comparable, V any](opts ...clock.Option) Option[K, V] {
+	return func(o *options[K, V]) {
+		o.cache = clock.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.

clock/clock.go

@@ -0,0 +1,140 @@
+package clock
+
+import (
+	"container/ring"
+)
+
+// Cache is used The clock cache replacement policy.
+//
+// The clock algorithm keeps a circular list of pages in memory, with
+// the "hand" (iterator) pointing to the last examined page frame in the list.
+// When a page fault occurs and no empty frames exist, then the R (referenced) bit
+// is inspected at the hand's location. If R is 0, the new page is put in place of
+// the page the "hand" points to, and the hand is advanced one position. Otherwise,
+// the R bit is cleared, then the clock hand is incremented and the process is
+// repeated until a page is replaced.
+type Cache[K comparable, V any] struct {
+	items    map[K]*ring.Ring
+	hand     *ring.Ring
+	head     *ring.Ring
+	capacity int
+}
+
+type entry[K comparable, V any] struct {
+	key            K
+	val            V
+	referenceCount int
+}
+
+// Option is an option for clock 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 clock 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)
+	}
+	r := ring.New(o.capacity)
+	return &Cache[K, V]{
+		items:    make(map[K]*ring.Ring, o.capacity),
+		hand:     r,
+		head:     r,
+		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 e, ok := c.items[key]; ok {
+		entry := e.Value.(*entry[K, V])
+		entry.referenceCount++
+		entry.val = val
+		return
+	}
+	c.evict()
+	c.hand.Value = &entry[K, V]{
+		key:            key,
+		val:            val,
+		referenceCount: 1,
+	}
+	c.items[key] = c.hand
+	c.hand = c.hand.Next()
+}
+
+// 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
+	}
+	entry := e.Value.(*entry[K, V])
+	entry.referenceCount = 1
+	return entry.val, true
+}
+
+func (c *Cache[K, V]) evict() {
+	if c.hand.Value == nil {
+		return
+	}
+	for c.hand.Value.(*entry[K, V]).referenceCount > 0 {
+		c.hand.Value.(*entry[K, V]).referenceCount--
+		c.hand = c.hand.Next()
+	}
+	entry := c.hand.Value.(*entry[K, V])
+	delete(c.items, entry.key)
+	c.hand.Value = nil
+}
+
+// Keys returns the keys of the cache. the order as same as current ring order.
+func (c *Cache[K, V]) Keys() []K {
+	keys := make([]K, 0, len(c.items))
+	r := c.head
+	if r.Value == nil {
+		return []K{}
+	}
+	// the first element
+	keys = append(keys, r.Value.(*entry[K, V]).key)
+
+	// iterating
+	for p := c.head.Next(); p != r; p = p.Next() {
+		if p.Value == nil {
+			break
+		}
+		e := p.Value.(*entry[K, V])
+		if e.referenceCount > 0 {
+			keys = append(keys, e.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 {
+		delete(c.items, key)
+		e.Value.(*entry[K, V]).referenceCount = 0
+	}
+}
+
+// Len returns the number of items in the cache.
+func (c *Cache[K, V]) Len() int {
+	return len(c.items)
+}

clock/clock_test.go

@@ -0,0 +1,132 @@
+package clock_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/Code-Hex/go-generics-cache/clock"
+)
+
+func TestSet(t *testing.T) {
+	// set capacity is 1
+	cache := clock.NewCache[string, int](clock.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 := clock.NewCache[string, int](clock.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) {
+	t.Run("normal", func(t *testing.T) {
+		cache := clock.NewCache[string, int]()
+		if len(cache.Keys()) != 0 {
+			t.Errorf("want number of keys 0, but got %d", cache.Len())
+		}
+
+		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())
+		}
+	})
+
+	t.Run("with deletion", func(t *testing.T) {
+		cache := clock.NewCache[string, int](clock.WithCapacity(4))
+		cache.Set("foo", 1)
+		cache.Set("bar", 2)
+		cache.Set("baz", 3)
+
+		cache.Delete("bar") // delete in middle
+
+		got := strings.Join(cache.Keys(), ",")
+		want := strings.Join([]string{
+			"foo",
+			"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())
+		}
+
+		cache.Set("hoge", 4)
+		cache.Set("fuga", 5) // over the cap. so expected to set "bar" position.
+
+		got2 := strings.Join(cache.Keys(), ",")
+		want2 := strings.Join([]string{
+			"foo",
+			"fuga",
+			"baz",
+			"hoge",
+		}, ",")
+		if got2 != want2 {
+			t.Errorf("want2 %q, but got2 %q", want, got)
+		}
+		if len(cache.Keys()) != cache.Len() {
+			t.Errorf("want2 number of keys %d, but got2 %d", len(cache.Keys()), cache.Len())
+		}
+	})
+}

clock/example_test.go

@@ -0,0 +1,49 @@
+package clock_test
+
+import (
+	"fmt"
+
+	"github.com/Code-Hex/go-generics-cache/clock"
+)
+
+func ExampleCache() {
+	c := clock.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 := clock.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
+}

example_test.go

@@ -20,6 +20,19 @@ func ExampleCache() {
 	// 0 false
 }
 
+func ExampleCacheAsClock() {
+	// use clock cache algorithm.
+	c := cache.New(cache.AsClock[string, int]())
+	c.Set("a", 1)
+	gota, aok := c.Get("a")
+	gotb, bok := c.Get("b")
+	fmt.Println(gota, aok)
+	fmt.Println(gotb, bok)
+	// Output:
+	// 1 true
+	// 0 false
+}
+
 func ExampleCacheWithExpiration() {
 	c := cache.New(cache.AsFIFO[string, int]())
 	exp := 250 * time.Millisecond