feat: Improve Redis synchronization for SetCache and NumericCache, and introduce comprehensive performance benchmarks.

Author: mysamimi

BENCHMARKS.md

@@ -0,0 +1,45 @@
+# go-cache Performance Benchmarks
+
+This document provides performance metrics for the `go-cache` library. Benchmarks were conducted on a high-performance system to establish baseline expectations.
+
+## System Specifications
+
+- **OS**: macOS (Darwin)
+- **Arch**: arm64
+- **CPU**: Apple M3 Max
+- **Go Version**: 1.2x
+
+## Benchmark Results
+
+| Benchmark | Iterations | Time (ns/op) | Memory (B/op) | Allocs (allocs/op) |
+|-----------|------------|--------------|---------------|-------------------|
+| **Local Cache** | | | | |
+| `Cache.Set` | 78,995,493 | 15.19 | 0 | 0 |
+| `Cache.Get` | 167,563,831 | 7.15 | 0 | 0 |
+| `ShardedCache.Set` (Parallel) | 21,197,948 | 56.81 | 35 | 2 |
+| `ShardedCache.Get` (Parallel) | 63,926,983 | 19.51 | 13 | 1 |
+| `NumericCache.Incr` | 45,319,717 | 25.78 | 0 | 0 |
+| **Set Cache** | | | | |
+| `SetCache.AddMember` | 210,420 | 5,733.00 | 5,474 | 5 |
+| `SetCache.Count` (100 members) | 320,437 | 3,428.00 | 0 | 0 |
+| **Redis Integrated** | | | | |
+| `Redis.Set` (Async Write) | 47,962,658 | 22.05 | 0 | 0 |
+| `Redis.Get` (Fallback/Network) | 3,790 | 272,521.00 | 1,024 | 17 |
+| `RedisNumeric.Incr` (with Sync) | 39,642,016 | 29.91 | 0 | 0 |
+
+## Analysis
+
+### 1. Local Cache Efficiency
+The standard `Cache` operations are extremely fast, measuring around **7-15 nanoseconds** per operation with zero allocations. This makes it ideal for high-frequency access patterns on single instances.
+
+### 2. Sharding Overhead vs. Scale
+While `ShardedCache` shows higher latency for small benchmarks due to hashing and bucket selection, it is recommended for high-concurrency environments to eliminate lock contention on the global map.
+
+### 3. Redis Synchronization
+With the new synchronization logic, `RedisNumeric.Incr` remains highly efficient (~30ns) because it only performs a network read when necessary. The `Redis.Get` fallback demonstrates the expected network latency (~0.27ms) when data must be fetched from an external Redis instance.
+
+### 4. SetCache Complexity
+`SetCache.AddMember` is the most expensive operation (~5.7µs) because it involves deep-copying the member map to ensure thread safety and consistency during modifications. This is a tradeoff for the rich feature set (per-member TTLs).
+
+---
+*Note: Benchmarks were run using `go test -bench=. -benchmem`. Actual performance may vary depending on hardware, network latency to Redis, and workload characteristics.*

README.md

@@ -16,6 +16,7 @@ go-cache is an in-memory key:value store/cache similar to memcached that is suit
 *   **Set Cache**: Track unique members per key, each with its own TTL — ideal for counting active sessions/devices per user.
 *   **Graceful Shutdown**: Ensures pending Redis operations are completed before exit.
 *   **Sync**: Force refresh items from Redis.
+*   **Performance**: Extremely low latency local operations (see [BENCHMARKS.md](BENCHMARKS.md)).
 
 ### Installation
 
@@ -66,7 +67,7 @@ val, found := c.Get("foo")
 
 ### Redis Integration (L2 Cache & Persistence)
 
-Writes (Set/Delete/ModifyNumeric) are **asynchronous** to Redis. Reads fall through to Redis when a key is missing locally.
+Writes (Set/Delete/ModifyNumeric) are **asynchronous** to Redis. However, modification operations like `ModifyNumeric` and `AddMember` will automatically **synchronize** with Redis before updating the local cache to ensure consistency across multiple instances.
 
 Supports both `go-redis/v8` and `go-redis/v9` via adapters.
 
@@ -260,13 +261,13 @@ defer ssc.Close()
 
 #### SetCache + Redis
 
-When Redis is attached, the `setData` (the member→expiry map) is persisted as JSON. This means the set survives application restarts and is shared across instances.
+When Redis is attached, the `setData` (the member→expiry map) is persisted as JSON. Shared across instances, the set automatically **synchronizes** with Redis during modification operations (like `AddMember`), ensuring that updates from one worker are visible to others.
 
 ```go
 sc := cache.NewSetCache(5*time.Minute, 10*time.Minute)
 sc.WithRedis(redisv9.New(rdb))
 defer sc.Close()
 
 sc.AddMember("user:42", "device-abc", 30*time.Second, 5*time.Minute)
-// Writes asynchronously to Redis key "user:42"
+// Fetches latest set data from Redis, merges change, then writes back asynchronously
 ```

benchmarks_test.go

@@ -0,0 +1,167 @@
+package cache
+
+import (
+	"context"
+	"fmt"
+	"testing"
+	"time"
+
+	"github.com/redis/go-redis/v9"
+)
+
+// --- Basic Cache Benchmarks ---
+
+func BenchmarkCache_Set(b *testing.B) {
+	c := New[int](DefaultExpiration, 0)
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		c.Set("key", i, DefaultExpiration)
+	}
+}
+
+func BenchmarkCache_Get(b *testing.B) {
+	c := New[int](DefaultExpiration, 0)
+	c.Set("key", 1, DefaultExpiration)
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = c.Get("key")
+	}
+}
+
+func BenchmarkShardedCache_Set(b *testing.B) {
+	c := NewShardedCache[int](32, DefaultExpiration, 0)
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		i := 0
+		for pb.Next() {
+			c.Set(fmt.Sprintf("key-%d", i), i, DefaultExpiration)
+			i++
+		}
+	})
+}
+
+func BenchmarkShardedCache_Get(b *testing.B) {
+	c := NewShardedCache[int](32, DefaultExpiration, 0)
+	for i := 0; i < 1000; i++ {
+		c.Set(fmt.Sprintf("key-%d", i), i, DefaultExpiration)
+	}
+	b.ResetTimer()
+	b.RunParallel(func(pb *testing.PB) {
+		i := 0
+		for pb.Next() {
+			_, _ = c.Get(fmt.Sprintf("key-%d", i%1000))
+			i++
+		}
+	})
+}
+
+func BenchmarkCache_WithCapacity_Set(b *testing.B) {
+	c := New[int](DefaultExpiration, 0)
+	c.WithCapacity(1000)
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		c.Set(fmt.Sprintf("key-%d", i), i, DefaultExpiration)
+	}
+}
+
+// --- Numeric Cache Benchmarks ---
+
+func BenchmarkNumericCache_Incr(b *testing.B) {
+	nc := &NumericCache[int]{New[int](DefaultExpiration, 0).cache}
+	nc.Set("counter", 0, DefaultExpiration)
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = nc.Incr("counter", 1)
+	}
+}
+
+// --- Set Cache Benchmarks ---
+
+func BenchmarkSetCache_Add(b *testing.B) {
+	sc := NewSetCache(DefaultExpiration, 0)
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		sc.AddMember("key", fmt.Sprintf("mem-%d", i%100), time.Minute, time.Minute)
+	}
+}
+
+func BenchmarkSetCache_Count_100(b *testing.B) {
+	sc := NewSetCache(DefaultExpiration, 0)
+	for i := 0; i < 100; i++ {
+		sc.AddMember("key", fmt.Sprintf("mem-%d", i), time.Minute, time.Minute)
+	}
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_ = sc.Count("key")
+	}
+}
+
+// --- Redis Integrated Benchmarks ---
+
+func BenchmarkRedisCache_Set_Async(b *testing.B) {
+	rdb := getRedisClientForBench()
+	if rdb == nil {
+		b.Skip("Redis not available")
+	}
+	c := New[int](DefaultExpiration, 0)
+	c.WithRedis(rdb)
+	defer c.Close()
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		c.Set("bench_key", i, DefaultExpiration)
+	}
+}
+
+func BenchmarkRedisCache_Get_Fallback(b *testing.B) {
+	rdb := getRedisClientForBench()
+	if rdb == nil {
+		b.Skip("Redis not available")
+	}
+	c := New[int](DefaultExpiration, 0)
+	c.WithRedis(rdb)
+	defer c.Close()
+
+	key := "bench_fallback_key"
+	c.Set(key, 123, DefaultExpiration)
+	time.Sleep(100 * time.Millisecond) // Wait for async write
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		c.Flush() // Clear local to force fallback
+		_, _ = c.Get(key)
+	}
+}
+
+func BenchmarkRedisNumeric_Incr_Sync(b *testing.B) {
+	rdb := getRedisClientForBench()
+	if rdb == nil {
+		b.Skip("Redis not available")
+	}
+	nc := &NumericCache[int]{New[int](DefaultExpiration, 0).cache}
+	nc.WithRedis(rdb)
+	defer nc.Close()
+
+	key := "bench_nc_sync"
+	nc.Set(key, 0, DefaultExpiration)
+	time.Sleep(100 * time.Millisecond)
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		_, _ = nc.Incr(key, 1)
+	}
+}
+
+// --- Helpers ---
+
+func getRedisClientForBench() RedisClient {
+	rdb := redis.NewClient(&redis.Options{
+		Addr: "localhost:6379",
+	})
+	ctx := context.Background()
+	if err := rdb.Ping(ctx).Err(); err != nil {
+		return nil
+	}
+	rdb.FlushDB(ctx)
+	return &RedisAdapter{client: rdb}
+}

cache.go

@@ -381,6 +381,12 @@ type NumericCache[N Number] struct {
 	*cache[N]
 }
 
+// WithRedis attaches a Redis L2 layer.
+func (c *NumericCache[N]) WithRedis(cli RedisClient) *NumericCache[N] {
+	c.withRedis(cli)
+	return c
+}
+
 // ModifyNumeric atomically modifies a numeric item in the cache.
 // If the item does not exist or is expired, it is set to `operand`.
 // If isIncrement is true, `operand` is added to the existing value.

set_cache.go

@@ -254,14 +254,12 @@ func (sc *SetCache) OnEvicted(f func(string, setData)) {
 // loadSet returns a mutable copy of the setData for key, creating one if absent/expired.
 // Caller must hold c.mu write-lock.
 func (sc *SetCache) loadSet(key string) setData {
-	item, found := sc.c.items[key]
-	if !found || item.Expired() {
-		if val, ttl, ok := sc.c.fetchFromRedis(key); ok {
-			sc.c.setLocal(key, val, ttl)
-			item = sc.c.items[key]
-			found = true
-		}
+	// Prioritize Redis fetch to ensure synchronization across instances
+	if val, ttl, ok := sc.c.fetchFromRedis(key); ok {
+		sc.c.setLocal(key, val, ttl)
 	}
+
+	item, found := sc.c.items[key]
 	if !found || item.Expired() {
 		return make(setData)
 	}
@@ -273,7 +271,6 @@ func (sc *SetCache) loadSet(key string) setData {
 	return cp
 }
 
-
 // liveCount counts non-expired entries in sd (nil-safe).
 func liveCount(sd setData) (n int) {
 	for _, item := range sd {

set_cache_test.go

@@ -385,39 +385,4 @@ func TestShardedSetCache_DeleteSet(t *testing.T) {
 	}
 }
 
-// ---------------------------------------------------------------------------
-// Benchmark
-// ---------------------------------------------------------------------------
-
-func BenchmarkSetCache_AddMember(b *testing.B) {
-	sc := NewSetCache(5*time.Minute, 0)
-	b.ResetTimer()
-	for i := 0; i < b.N; i++ {
-		sc.AddMember("user:1", fmt.Sprintf("device-%d", i%50), 30*time.Second, 5*time.Minute)
-	}
-}
-
-func BenchmarkSetCache_CheckAndClean(b *testing.B) {
-	sc := NewSetCache(5*time.Minute, 0)
-	for i := 0; i < 20; i++ {
-		sc.AddMember("user:1", fmt.Sprintf("device-%d", i), 30*time.Second, 5*time.Minute)
-	}
-	b.ResetTimer()
-	for i := 0; i < b.N; i++ {
-		sc.CheckAndClean("user:1", fmt.Sprintf("device-%d", i%20), 50)
-	}
-}
-
-func BenchmarkShardedSetCache_AddMember(b *testing.B) {
-	ssc := NewShardedSetCache(16, 5*time.Minute, 0)
-	b.ResetTimer()
-	b.RunParallel(func(pb *testing.PB) {
-		i := 0
-		for pb.Next() {
-			key := fmt.Sprintf("user:%d", i%100)
-			member := fmt.Sprintf("device-%d", i%50)
-			ssc.AddMember(key, member, 30*time.Second, 5*time.Minute)
-			i++
-		}
-	})
-}
+// (Benchmarks moved to benchmarks_test.go)

sharded_redis_test.go

@@ -247,6 +247,17 @@ func TestRedisIntegration_NumericAndSet(t *testing.T) {
 
 		// Worker2 adds a DIFFERENT member to the SAME set
 		worker2.AddMember(key, "session2", time.Minute, time.Minute)
+		time.Sleep(1000 * time.Millisecond) // wait for async redis write
+
+		cnt, isNew := worker1.AddMember(key, "session1", time.Minute, time.Minute)
+		time.Sleep(1000 * time.Millisecond) // wait for async redis write
+
+		if isNew {
+			t.Errorf("Worker1 added a duplicate session. Expected false, got %v", isNew)
+		}
+		if cnt != 2 {
+			t.Errorf("Worker1 added a duplicate session. Expected 2, got %d (isNew: %v)", cnt, isNew)
+		}
 
 		// Worker2 should now see BOTH sessions
 		count := worker2.Count(key)