feat: add cache front/back method to get the first/last element

Author: sanad haj yahya

arc/arc.go

@@ -32,6 +32,20 @@ type arc struct {
 	b2 *internal.Cache
 }
 
+func (a *arc) Front() interface{} {
+	if k := a.t1.Front(); k != nil {
+		return k
+	}
+	return a.t2.Front()
+}
+
+func (a *arc) Back() interface{} {
+	if k := a.t1.Back(); k != nil {
+		return k
+	}
+	return a.t2.Back()
+}
+
 func (a *arc) Load(key interface{}) (value interface{}, ok bool) {
 	if val, ok := a.t1.Peek(key); ok {
 		exp, _ := a.t1.Expiry(key)

arc/arc_test.go

@@ -53,8 +53,11 @@ func TestARCc(t *testing.T) {
 
 	a.Store(1, 1)
 	a.Load(1)
+
 	assert.Equal(t, 0, a.t1.Len())
 	assert.Equal(t, 1, a.t2.Len())
+	assert.Equal(t, 1, a.Front())
+	assert.Equal(t, 1, a.Back())
 
 	a.Delete(1)
 }

cache.go

@@ -24,6 +24,20 @@ type Event = internal.Event
 
 // Cache stores data so that future requests for that data can be served faster.
 type Cache interface {
+	// Front returns the first key of cache or nil if the cache is empty.
+	//
+	// # Experimental
+	//
+	// Notice: This func is EXPERIMENTAL and may be changed or removed in a
+	// later release.
+	Front() interface{}
+	// Back returns the last key of cache or nil if the cache is empty.
+	//
+	// # Experimental
+	//
+	// Notice: This func is EXPERIMENTAL and may be changed or removed in a
+	// later release.
+	Back() interface{}
 	// Load returns key value.
 	Load(key interface{}) (interface{}, bool)
 	// Peek returns key value without updating the underlying "recent-ness".
@@ -91,7 +105,7 @@ type Cache interface {
 // GC is a long running function, it returns when ctx done, therefore the
 // caller must start it in its own goroutine.
 //
-// Experimental
+// # Experimental
 //
 // Notice: This func is EXPERIMENTAL and may be changed or removed in a
 // later release.
@@ -142,6 +156,20 @@ type cache struct {
 	unsafe Cache
 }
 
+func (c *cache) Front() interface{} {
+	c.mu.Lock()
+	k := c.unsafe.Front()
+	c.mu.Unlock()
+	return k
+}
+
+func (c *cache) Back() interface{} {
+	c.mu.Lock()
+	k := c.unsafe.Back()
+	c.mu.Unlock()
+	return k
+}
+
 func (c *cache) Load(key interface{}) (interface{}, bool) {
 	c.mu.Lock()
 	v, ok := c.unsafe.Load(key)

fifo/fifo.go

@@ -42,6 +42,20 @@ func (c *collection) Discard() (e *internal.Entry) {
 	return
 }
 
+func (c *collection) Front() (e *internal.Entry) {
+	if le := c.ll.Front(); le != nil {
+		e = le.Value.(*internal.Entry)
+	}
+	return
+}
+
+func (c *collection) Back() (e *internal.Entry) {
+	if le := c.ll.Back(); le != nil {
+		e = le.Value.(*internal.Entry)
+	}
+	return
+}
+
 func (c *collection) Len() int {
 	return c.ll.Len()
 }

fifo/fifo_test.go

@@ -28,11 +28,14 @@ func TestCollection(t *testing.T) {
 		}
 	}
 
+	front := c.Front()
+	back := c.Back()
 	oldest := c.Discard()
 	c.Remove(entries[2])
-	back := c.ll.Back().Value.(*internal.Entry)
 
+	assert.Equal(t, 1, front.Key)
+	assert.Equal(t, 3, back.Key)
 	assert.Equal(t, 1, oldest.Key)
 	assert.Equal(t, 1, c.Len())
-	assert.Equal(t, 2, back.Key)
+	assert.Equal(t, 2, c.Back().Key)
 }

idle/idle.go

@@ -18,6 +18,8 @@ func New(cap int) libcache.Cache {
 
 type idle struct{}
 
+func (idle) Front() (v interface{})                               { return }
+func (idle) Back() (v interface{})                                { return }
 func (idle) Load(interface{}) (v interface{}, ok bool)            { return }
 func (idle) Peek(interface{}) (v interface{}, ok bool)            { return }
 func (idle) Keys() (keys []interface{})                           { return }

internal/cache.go

@@ -53,6 +53,8 @@ type Collection interface {
 	Add(*Entry)
 	Remove(*Entry)
 	Discard() *Entry
+	Front() *Entry
+	Back() *Entry
 	Len() int
 	Init()
 }
@@ -97,6 +99,30 @@ type Cache struct {
 	capacity int
 }
 
+// Front returns the first key of cache or nil if the cache is empty.
+func (c *Cache) Front() interface{} {
+	// Run GC inline before get the front entry.
+	c.GC()
+
+	if e := c.coll.Front(); e != nil {
+		return e.Key
+	}
+
+	return nil
+}
+
+// Back returns the last key of cache or nil if the cache is empty.
+func (c *Cache) Back() interface{} {
+	// Run GC inline before get the back entry.
+	c.GC()
+
+	if e := c.coll.Back(); e != nil {
+		return e.Key
+	}
+
+	return nil
+}
+
 // Load returns key value.
 func (c *Cache) Load(key interface{}) (interface{}, bool) {
 	return c.get(key, false)

lfu/lfu.go

@@ -57,6 +57,20 @@ func (f *collection) Discard() (e *internal.Entry) {
 	return heap.Pop(f).(*element).value
 }
 
+func (f *collection) Front() (e *internal.Entry) {
+	if f.Len() > 0 {
+		e = (*f)[f.Len()-1].value
+	}
+	return
+}
+
+func (f *collection) Back() (e *internal.Entry) {
+	if f.Len() > 0 {
+		e = (*f)[0].value
+	}
+	return
+}
+
 func (f *collection) Move(e *internal.Entry) {
 	ele := e.Element.(*element)
 	ele.count++

lfu/lfu_test.go

@@ -27,9 +27,13 @@ func TestCollection(t *testing.T) {
 		}
 	}
 
+	front := f.Front()
+	back := f.Back()
 	oldest := f.Discard()
 	f.Remove(entries[2])
 
+	assert.Equal(t, front.Key, 2)
+	assert.Equal(t, back.Key, 1)
 	assert.Equal(t, oldest.Key, 1)
 	assert.Equal(t, f.Len(), 1)
 	assert.Equal(t, (*f)[0].value.Key, 2)

lifo/lifo.go

@@ -42,6 +42,20 @@ func (c *collection) Discard() (e *internal.Entry) {
 	return
 }
 
+func (c *collection) Front() (e *internal.Entry) {
+	if le := c.ll.Front(); le != nil {
+		e = le.Value.(*internal.Entry)
+	}
+	return
+}
+
+func (c *collection) Back() (e *internal.Entry) {
+	if le := c.ll.Back(); le != nil {
+		e = le.Value.(*internal.Entry)
+	}
+	return
+}
+
 func (c *collection) Len() int {
 	return c.ll.Len()
 }

lifo/lifo_test.go

@@ -28,11 +28,15 @@ func TestCollection(t *testing.T) {
 		}
 	}
 
+	front := c.Front()
+	back := c.Back()
+
 	oldest := c.Discard()
 	c.Remove(entries[0])
-	back := c.ll.Back().Value.(*internal.Entry)
 
+	assert.Equal(t, 1, front.Key)
+	assert.Equal(t, 3, back.Key)
 	assert.Equal(t, 3, oldest.Key)
 	assert.Equal(t, 1, c.Len())
-	assert.Equal(t, 2, back.Key)
+	assert.Equal(t, 2, c.Back().Key)
 }

lru/lru.go

@@ -45,6 +45,20 @@ func (c *collection) Discard() (e *internal.Entry) {
 	return
 }
 
+func (c *collection) Front() (e *internal.Entry) {
+	if le := c.ll.Front(); le != nil {
+		e = le.Value.(*internal.Entry)
+	}
+	return
+}
+
+func (c *collection) Back() (e *internal.Entry) {
+	if le := c.ll.Back(); le != nil {
+		e = le.Value.(*internal.Entry)
+	}
+	return
+}
+
 func (c *collection) Len() int {
 	return c.ll.Len()
 }

lru/lru_test.go

@@ -28,11 +28,15 @@ func TestCollection(t *testing.T) {
 		}
 	}
 
+	front := c.Front()
+	back := c.Back()
+
 	oldest := c.Discard()
 	c.Remove(entries[2])
-	back := c.ll.Back().Value.(*internal.Entry)
 
+	assert.Equal(t, 3, front.Key)
+	assert.Equal(t, 1, back.Key)
 	assert.Equal(t, 1, oldest.Key)
 	assert.Equal(t, 1, c.Len())
-	assert.Equal(t, 2, back.Key)
+	assert.Equal(t, 2, c.Back().Key)
 }

mru/mru.go

@@ -45,6 +45,20 @@ func (c *collection) Discard() (e *internal.Entry) {
 	return
 }
 
+func (c *collection) Front() (e *internal.Entry) {
+	if le := c.ll.Front(); le != nil {
+		e = le.Value.(*internal.Entry)
+	}
+	return
+}
+
+func (c *collection) Back() (e *internal.Entry) {
+	if le := c.ll.Back(); le != nil {
+		e = le.Value.(*internal.Entry)
+	}
+	return
+}
+
 func (c *collection) Len() int {
 	return c.ll.Len()
 }

mru/mru_test.go

@@ -28,11 +28,14 @@ func TestCollection(t *testing.T) {
 		}
 	}
 
+	front := c.Front()
+	back := c.Back()
 	oldest := c.Discard()
 	c.Remove(entries[1])
-	back := c.ll.Back().Value.(*internal.Entry)
 
+	assert.Equal(t, 3, front.Key)
+	assert.Equal(t, 1, back.Key)
 	assert.Equal(t, 3, oldest.Key)
 	assert.Equal(t, 1, c.Len())
-	assert.Equal(t, 1, back.Key)
+	assert.Equal(t, 1, c.Back().Key)
 }