chore: expose gc api

Author: shaj13

arc/arc.go

@@ -184,6 +184,21 @@ func (a *arc) Notify(fn func(libcache.Event), ops ...libcache.Op) {
 	a.t2.Notify(fn, ops...)
 }
 
+func (a *arc) GC() time.Duration {
+	x := a.t1.GC()
+	y := a.t2.GC()
+
+	// return the next nearer gc cycle.
+	if y == 0 {
+		return x
+	} else if x == 0 {
+		return y
+	} else if x < y {
+		return x
+	}
+	return y
+}
+
 func min(x, y int) int {
 	if x < y {
 		return x

cache.go

@@ -63,11 +63,18 @@ type Cache interface {
 	//
 	// Deprecated: use Notify instead.
 	RegisterOnExpired(f func(key, value interface{}))
-
 	// Notify causes cahce to relay events to fn.
 	// If no operations are provided, all incoming operations will be relayed to fn.
 	// Otherwise, just the provided operations will.
 	Notify(fn func(Event), ops ...Op)
+	// GC runs a garbage collection and blocks the caller until the
+	// all expired items from the cache evicted.
+	//
+	// GC returns the remaining time duration for the next gc cycle
+	// if there any, Otherwise, it return 0.
+	//
+	// Calling GC without waits for the duration to elapsed considered a no-op.
+	GC() time.Duration
 }
 
 type cache struct {
@@ -194,3 +201,10 @@ func (c *cache) Expiry(key interface{}) (time.Time, bool) {
 	c.mu.Unlock()
 	return exp, ok
 }
+
+func (c *cache) GC() time.Duration {
+	c.mu.Lock()
+	dur := c.unsafe.GC()
+	c.mu.Unlock()
+	return dur
+}

cache_test.go

@@ -309,32 +309,6 @@ func TestExpiring(t *testing.T) {
 	}
 }
 
-func BenchmarkCache(b *testing.B) {
-	for _, tt := range cacheTests {
-		b.Run("Benchmark"+tt.cont.String()+"Cache", func(b *testing.B) {
-			keys := []interface{}{}
-			cache := tt.cont.New(0)
-
-			for i := 0; i < 100; i++ {
-				keys = append(keys, i)
-			}
-
-			b.ResetTimer()
-			b.RunParallel(func(pb *testing.PB) {
-				for pb.Next() {
-					key := keys[rand.Intn(100)]
-					_, ok := cache.Load(key)
-					if ok {
-						cache.Delete(key)
-					} else {
-						cache.Store(key, struct{}{})
-					}
-				}
-			})
-		})
-	}
-}
-
 func TestNotify(t *testing.T) {
 	for _, tt := range cacheTests {
 		t.Run("Test"+tt.cont.String()+"CacheNotify", func(t *testing.T) {
@@ -359,5 +333,46 @@ func TestNotify(t *testing.T) {
 			}
 		})
 	}
+}
+
+func TestGC(t *testing.T) {
+	for _, tt := range cacheTests {
+		t.Run("Test"+tt.cont.String()+"CacheGC", func(t *testing.T) {
+			cache := tt.cont.NewUnsafe(0)
+			cache.StoreWithTTL(0, 0, time.Nanosecond)
+			cache.StoreWithTTL(1, 1, time.Millisecond*100)
+			dur := cache.GC()
+
+			assert.GreaterOrEqual(t, int64(dur), int64(time.Millisecond*99))
+			time.Sleep(dur)
+
+			assert.Zero(t, int(cache.GC()))
+			assert.Zero(t, cache.Len())
+		})
+	}
+}
+func BenchmarkCache(b *testing.B) {
+	for _, tt := range cacheTests {
+		b.Run("Benchmark"+tt.cont.String()+"Cache", func(b *testing.B) {
+			keys := []interface{}{}
+			cache := tt.cont.New(0)
+
+			for i := 0; i < 100; i++ {
+				keys = append(keys, i)
+			}
 
+			b.ResetTimer()
+			b.RunParallel(func(pb *testing.PB) {
+				for pb.Next() {
+					key := keys[rand.Intn(100)]
+					_, ok := cache.Load(key)
+					if ok {
+						cache.Delete(key)
+					} else {
+						cache.Store(key, struct{}{})
+					}
+				}
+			})
+		})
+	}
 }

idle/idle.go

@@ -27,6 +27,7 @@ func (idle) Len() (len int)                                       { return }
 func (idle) Cap() (cap int)                                       { return }
 func (idle) TTL() (t time.Duration)                               { return }
 func (idle) Expiry(interface{}) (t time.Time, ok bool)            { return }
+func (idle) GC() (dur time.Duration)                              { return }
 func (idle) Update(interface{}, interface{})                      {}
 func (idle) Store(interface{}, interface{})                       {}
 func (idle) StoreWithTTL(interface{}, interface{}, time.Duration) {}

internal/cache.go

@@ -94,7 +94,7 @@ func (c *Cache) Peek(key interface{}) (interface{}, bool) {
 
 func (c *Cache) get(key interface{}, peek bool) (interface{}, bool) {
 	// Run GC inline before return the entry.
-	c.gc()
+	c.GC()
 
 	e, ok := c.entries[key]
 	if !ok {
@@ -127,7 +127,7 @@ func (c *Cache) Store(key, value interface{}) {
 // StoreWithTTL sets the key value with TTL overrides the default.
 func (c *Cache) StoreWithTTL(key, value interface{}, ttl time.Duration) {
 	// Run GC inline before pushing the new entry.
-	c.gc()
+	c.GC()
 
 	if e, ok := c.entries[key]; ok {
 		c.removeEntry(e)
@@ -152,7 +152,7 @@ func (c *Cache) StoreWithTTL(key, value interface{}, ttl time.Duration) {
 // Update the key value without updating the underlying "rank".
 func (c *Cache) Update(key, value interface{}) {
 	// Run GC inline before update the entry.
-	c.gc()
+	c.GC()
 
 	if c.Contains(key) {
 		e := c.entries[key]
@@ -265,14 +265,25 @@ func (c *Cache) emit(op Op, k, v interface{}, exp time.Time, ok bool) {
 	}
 }
 
-func (c *Cache) gc() {
+// GC returns the remaining time duration for the next gc cycle if there any,
+// Otherwise, it return 0.
+//
+// Calling GC without waits for the duration to elapsed considered a no-op.
+func (c *Cache) GC() time.Duration {
 	now := time.Now()
 	for {
+
 		// Return from gc if the heap is empty or the next element is not yet
-		// expired
-		if len(c.heap) == 0 || now.Before(c.heap[0].Exp) {
-			return
+		// expired.
+
+		if len(c.heap) == 0 {
+			return 0
 		}
+
+		if now.Before(c.heap[0].Exp) {
+			return c.heap[0].Exp.Sub(now)
+		}
+
 		e := heap.Pop(&c.heap).(*Entry)
 		c.evict(e)
 	}