16 shards

Author: Thomas Stromberg

cache.go

@@ -19,7 +19,7 @@ type Cache[K comparable, V any] struct {
 // New creates a new cache with the given options.
 func New[K comparable, V any](ctx context.Context, options ...Option) (*Cache[K, V], error) {
 	opts := &Options{
-		MemorySize: 10000,
+		MemorySize: 16384, // 2^14, divides evenly by 16 shards
 	}
 	for _, opt := range options {
 		opt(opts)
@@ -139,15 +139,15 @@ func (c *Cache[K, V]) Get(ctx context.Context, key K) (V, bool, error) {
 	return val, true, nil
 }
 
-// calculateExpiry returns the expiry time based on TTL and default TTL.
-func (c *Cache[K, V]) calculateExpiry(ttl time.Duration) time.Time {
-	if ttl > 0 {
-		return time.Now().Add(ttl)
+// expiry returns the expiry time based on TTL and default TTL.
+func (c *Cache[K, V]) expiry(ttl time.Duration) time.Time {
+	if ttl <= 0 {
+		ttl = c.opts.DefaultTTL
 	}
-	if c.opts.DefaultTTL > 0 {
-		return time.Now().Add(c.opts.DefaultTTL)
+	if ttl <= 0 {
+		return time.Time{}
 	}
-	return time.Time{}
+	return time.Now().Add(ttl)
 }
 
 // Set stores a value in the cache with an optional TTL.
@@ -162,7 +162,7 @@ func (c *Cache[K, V]) Set(ctx context.Context, key K, value V, ttl time.Duration
 		return nil
 	}
 
-	expiry := c.calculateExpiry(ttl)
+	expiry := c.expiry(ttl)
 
 	// Validate key early if persistence is enabled
 	if c.persist != nil {
@@ -188,7 +188,7 @@ func (c *Cache[K, V]) Set(ctx context.Context, key K, value V, ttl time.Duration
 // Key validation and in-memory caching happen synchronously. Persistence errors are logged but not returned.
 // Returns an error only for validation failures (e.g., invalid key format).
 func (c *Cache[K, V]) SetAsync(ctx context.Context, key K, value V, ttl time.Duration) error {
-	expiry := c.calculateExpiry(ttl)
+	expiry := c.expiry(ttl)
 
 	// Validate key early if persistence is enabled (synchronous)
 	if c.persist != nil {

cache_persist_test.go

@@ -593,15 +593,15 @@ func TestCache_GhostQueue(t *testing.T) {
 func TestCache_MainQueueEviction(t *testing.T) {
 	ctx := context.Background()
 
-	// Create cache with capacity divisible by 4 shards
-	cache, err := New[string, int](ctx, WithMemorySize(40))
+	// Create cache with capacity divisible by 16 shards (48 = 3 per shard)
+	cache, err := New[string, int](ctx, WithMemorySize(48))
 	if err != nil {
 		t.Fatalf("New: %v", err)
 	}
 	defer func() { _ = cache.Close() }() //nolint:errcheck // Test cleanup
 
 	// Insert and access items to get them into Main queue
-	for i := range 60 {
+	for i := range 72 {
 		key := fmt.Sprintf("key%d", i)
 		if err := cache.Set(ctx, key, i, 0); err != nil {
 			t.Fatalf("Set: %v", err)
@@ -611,17 +611,17 @@ func TestCache_MainQueueEviction(t *testing.T) {
 	}
 
 	// Insert more items to trigger eviction from Main queue
-	for i := range 40 {
-		key := fmt.Sprintf("key%d", i+60)
-		if err := cache.Set(ctx, key, i+60, 0); err != nil {
+	for i := range 48 {
+		key := fmt.Sprintf("key%d", i+100)
+		if err := cache.Set(ctx, key, i+100, 0); err != nil {
 			t.Fatalf("Set: %v", err)
 		}
 		_, _, _ = cache.Get(ctx, key) //nolint:errcheck // Exercising code path
 	}
 
 	// Verify cache is at capacity
-	if cache.Len() > 40 {
-		t.Errorf("Cache length %d exceeds capacity 40", cache.Len())
+	if cache.Len() > 48 {
+		t.Errorf("Cache length %d exceeds capacity 48", cache.Len())
 	}
 }
 

cache_test.go

@@ -360,8 +360,8 @@ func TestCache_New_DefaultOptions(t *testing.T) {
 		}
 	}()
 
-	if cache.opts.MemorySize != 10000 {
-		t.Errorf("default memory size = %d; want 10000", cache.opts.MemorySize)
+	if cache.opts.MemorySize != 16384 {
+		t.Errorf("default memory size = %d; want 16384", cache.opts.MemorySize)
 	}
 
 	if cache.opts.DefaultTTL != 0 {
@@ -544,29 +544,29 @@ func TestCache_DeleteNonExistent(t *testing.T) {
 
 func TestCache_EvictFromMain(t *testing.T) {
 	ctx := context.Background()
-	// Cache with capacity divisible by 4 shards
-	cache, err := New[int, int](ctx, WithMemorySize(40))
+	// Cache with capacity divisible by 16 shards (48 = 3 per shard)
+	cache, err := New[int, int](ctx, WithMemorySize(48))
 	if err != nil {
 		t.Fatalf("New: %v", err)
 	}
 	defer func() { _ = cache.Close() }() //nolint:errcheck // Test cleanup
 
 	// Fill small queue and promote items to main by accessing them twice
-	for i := range 60 {
+	for i := range 72 {
 		_ = cache.Set(ctx, i, i, 0) //nolint:errcheck // Test fixture
 		// Access immediately to promote to main
 		_, _, _ = cache.Get(ctx, i) //nolint:errcheck // Exercising code path
 	}
 
 	// Add more items to force eviction from main queue
-	for i := range 40 {
+	for i := range 48 {
 		_ = cache.Set(ctx, i+100, i+100, 0) //nolint:errcheck // Test fixture
 		_, _, _ = cache.Get(ctx, i+100)     //nolint:errcheck // Exercising code path
 	}
 
 	// Cache should not exceed capacity
-	if cache.Len() > 40 {
-		t.Errorf("cache length = %d; should not exceed 40", cache.Len())
+	if cache.Len() > 48 {
+		t.Errorf("cache length = %d; should not exceed 48", cache.Len())
 	}
 }
 

s3fifo.go

@@ -8,12 +8,12 @@ import (
 	"time"
 )
 
-const numShards = 4
+const numShards = 16
 
 // s3fifo implements the S3-FIFO eviction algorithm from SOSP'23 paper
 // "FIFO queues are all you need for cache eviction"
 //
-// This implementation uses 4-way sharding for improved concurrent performance.
+// This implementation uses 16-way sharding for improved concurrent performance.
 // Each shard is an independent S3-FIFO instance with its own queues and lock.
 //
 // Algorithm per shard:
@@ -63,7 +63,7 @@ type entry[K comparable, V any] struct {
 // newS3FIFO creates a new sharded S3-FIFO cache with the given total capacity.
 func newS3FIFO[K comparable, V any](capacity int) *s3fifo[K, V] {
 	if capacity <= 0 {
-		capacity = 10000
+		capacity = 16384 // 2^14, divides evenly by 16 shards
 	}
 
 	// Divide capacity across shards (round up to avoid zero-capacity shards)
@@ -102,20 +102,10 @@ func newShard[K comparable, V any](capacity int) *shard[K, V] {
 	}
 }
 
-// getShard returns the shard for a given key using maphash.
+// getShard returns the shard for a given key using type-optimized hashing.
 func (c *s3fifo[K, V]) getShard(key K) *shard[K, V] {
-	var h maphash.Hash
-	h.SetSeed(c.seed)
-	//nolint:errcheck,gosec // maphash.Hash.WriteString never returns error
-	h.WriteString(any(key).(string))
-	return c.shards[h.Sum64()%numShards]
-}
-
-// getShardInt is an optimized path for common key types.
-func (c *s3fifo[K, V]) getShardInt(key K) *shard[K, V] {
 	switch k := any(key).(type) {
 	case int:
-		// Safe: modulo result is always in [0, numShards)
 		if k < 0 {
 			k = -k
 		}
@@ -136,14 +126,19 @@ func (c *s3fifo[K, V]) getShardInt(key K) *shard[K, V] {
 		h.WriteString(k)
 		return c.shards[h.Sum64()%numShards]
 	default:
-		return c.getShard(key)
+		// Fallback for other types: convert to string and hash
+		var h maphash.Hash
+		h.SetSeed(c.seed)
+		//nolint:errcheck,gosec // maphash.Hash.WriteString never returns error
+		h.WriteString(any(key).(string))
+		return c.shards[h.Sum64()%numShards]
 	}
 }
 
 // getFromMemory retrieves a value from the in-memory cache.
 // On hit, increments frequency counter (used during eviction).
 func (c *s3fifo[K, V]) getFromMemory(key K) (V, bool) {
-	return c.getShardInt(key).get(key)
+	return c.getShard(key).get(key)
 }
 
 func (s *shard[K, V]) get(key K) (V, bool) {
@@ -176,7 +171,7 @@ func (s *shard[K, V]) get(key K) (V, bool) {
 
 // setToMemory adds or updates a value in the in-memory cache.
 func (c *s3fifo[K, V]) setToMemory(key K, value V, expiry time.Time) {
-	c.getShardInt(key).set(key, value, expiry)
+	c.getShard(key).set(key, value, expiry)
 }
 
 func (s *shard[K, V]) set(key K, value V, expiry time.Time) {
@@ -224,7 +219,7 @@ func (s *shard[K, V]) set(key K, value V, expiry time.Time) {
 
 // deleteFromMemory removes a value from the in-memory cache.
 func (c *s3fifo[K, V]) deleteFromMemory(key K) {
-	c.getShardInt(key).delete(key)
+	c.getShard(key).delete(key)
 }
 
 func (s *shard[K, V]) delete(key K) {
@@ -404,7 +399,7 @@ func (c *s3fifo[K, V]) queueLens() (small, main int) {
 
 // isInSmall returns whether a key is in the small queue (for testing).
 func (c *s3fifo[K, V]) isInSmall(key K) bool {
-	s := c.getShardInt(key)
+	s := c.getShard(key)
 	s.mu.RLock()
 	defer s.mu.RUnlock()
 	if ent, ok := s.items[key]; ok {
@@ -415,7 +410,7 @@ func (c *s3fifo[K, V]) isInSmall(key K) bool {
 
 // setExpiry sets the expiry time for a key (for testing).
 func (c *s3fifo[K, V]) setExpiry(key K, expiry time.Time) {
-	s := c.getShardInt(key)
+	s := c.getShard(key)
 	s.mu.Lock()
 	defer s.mu.Unlock()
 	if ent, ok := s.items[key]; ok {

s3fifo_test.go

@@ -36,8 +36,8 @@ func TestS3FIFO_BasicOperations(t *testing.T) {
 }
 
 func TestS3FIFO_Capacity(t *testing.T) {
-	capacity := 100
-	cache := newS3FIFO[int, string](capacity)
+	cache := newS3FIFO[int, string](100)
+	capacity := cache.totalCapacity() // Actual capacity after shard rounding
 
 	// Fill cache to capacity
 	for i := range capacity {
@@ -57,27 +57,28 @@ func TestS3FIFO_Capacity(t *testing.T) {
 }
 
 func TestS3FIFO_Eviction(t *testing.T) {
-	cache := newS3FIFO[int, int](100) // Use larger capacity for predictable behavior
+	cache := newS3FIFO[int, int](100)
+	capacity := cache.totalCapacity() // Actual capacity after shard rounding
 
 	// Fill to capacity
-	for i := range 100 {
+	for i := range capacity {
 		cache.setToMemory(i, i, time.Time{})
 	}
 
 	// Access item 0 to increase its frequency
 	cache.getFromMemory(0)
 
 	// Add one more item - should evict least frequently used
-	cache.setToMemory(1000, 99, time.Time{})
+	cache.setToMemory(capacity+1000, 99, time.Time{})
 
 	// Item 0 should still exist (it was accessed)
 	if _, ok := cache.getFromMemory(0); !ok {
 		t.Error("item 0 was evicted but should have been promoted")
 	}
 
 	// Should be at capacity
-	if cache.memoryLen() != 100 {
-		t.Errorf("cache length = %d; want 100", cache.memoryLen())
+	if cache.memoryLen() != capacity {
+		t.Errorf("cache length = %d; want %d", cache.memoryLen(), capacity)
 	}
 }
 
@@ -126,7 +127,7 @@ func TestS3FIFO_TTL(t *testing.T) {
 }
 
 func TestS3FIFO_Cleanup(t *testing.T) {
-	cache := newS3FIFO[string, int](10)
+	cache := newS3FIFO[string, int](100)
 
 	// Add some items with different expiries
 	now := time.Now()
@@ -157,6 +158,7 @@ func TestS3FIFO_Cleanup(t *testing.T) {
 
 func TestS3FIFO_Concurrent(t *testing.T) {
 	cache := newS3FIFO[int, int](1000)
+	capacity := cache.totalCapacity()
 	var wg sync.WaitGroup
 
 	// Concurrent writers
@@ -183,14 +185,15 @@ func TestS3FIFO_Concurrent(t *testing.T) {
 
 	wg.Wait()
 
-	// Cache should be at capacity
-	if cache.memoryLen() != 1000 {
-		t.Errorf("cache length = %d; want 1000", cache.memoryLen())
+	// Cache should be at or below capacity (we wrote exactly 1000 items)
+	if cache.memoryLen() > capacity {
+		t.Errorf("cache length = %d; want <= %d", cache.memoryLen(), capacity)
 	}
 }
 
 func TestS3FIFO_FrequencyPromotion(t *testing.T) {
-	cache := newS3FIFO[string, int](10)
+	cache := newS3FIFO[string, int](100)
+	capacity := cache.totalCapacity()
 
 	// Add items - they start in small queue
 	cache.setToMemory("key0", 0, time.Time{})
@@ -200,8 +203,8 @@ func TestS3FIFO_FrequencyPromotion(t *testing.T) {
 	cache.getFromMemory("key0")
 
 	// Fill to capacity
-	for i := 2; i < 10; i++ {
-		cache.setToMemory("key"+string(rune('0'+i)), i, time.Time{})
+	for i := 2; i < capacity; i++ {
+		cache.setToMemory(fmt.Sprintf("key%d", i), i, time.Time{})
 	}
 
 	// Add one more to trigger eviction
@@ -241,11 +244,11 @@ func TestS3FIFO_SmallCapacity(t *testing.T) {
 }
 
 func TestS3FIFO_ZeroCapacity(t *testing.T) {
-	// Zero capacity should default to 10000
+	// Zero capacity should default to 16384
 	cache := newS3FIFO[string, int](0)
 
-	if cache.totalCapacity() != 10000 {
-		t.Errorf("total capacity = %d; want 10000", cache.totalCapacity())
+	if cache.totalCapacity() != 16384 {
+		t.Errorf("total capacity = %d; want 16384", cache.totalCapacity())
 	}
 }