add string fast path

Author: Thomas Stromberg

README.md

@@ -8,7 +8,7 @@
 
 <br clear="right">
 
-Blazing fast in-memory Go cache with optional L2 persistence layer.
+Stupid fast in-memory Go cache with optional L2 persistence layer.
 
 ## Install
 
@@ -65,8 +65,6 @@ cache, _ := bdcache.New[string, User](ctx,
 bdcache prioritizes high hit-rates and low read latency, but it performs quite well all around.
 
 Here's the results from an M4 MacBook Pro - run `make bench` to see the results for yourself:
-```
-════════════════════════════════════════════════════════════════════════════╝
 
 ### Hit Rate (Zipf α=0.99, 1M ops, 1M keyspace)
 
@@ -192,9 +190,8 @@ Here's the results from an M4 MacBook Pro - run `make bench` to see the results
 
 🏆 Get throughput: +0.9% faster than 2nd best (otter)
 🏆 Set throughput: +9.1% faster than 2nd best (freecache)
-```
 
-There will certainly be benchmarks where other caches perform faster, but no solution blends speed and persistence the way that bdcache does.
+NOTE: Performance characteristics often have trade-offs. There are almost certainly workloads where other cache implementations are faster, but nobody blends speed and persistence the way that bdcache does.
 
 ## License
 

s3fifo.go

@@ -37,10 +37,11 @@ const (
 //   - If freq == 0 → evict (don't add to ghost, already there)
 //   - If freq > 0 → reinsert to back of Main and decrement freq (lazy promotion)
 type s3fifo[K comparable, V any] struct {
-	shards     [numShards]*shard[K, V]
-	seed       maphash.Seed
-	keyIsInt   bool // Fast path flag for int keys
-	keyIsInt64 bool // Fast path flag for int64 keys
+	shards      [numShards]*shard[K, V]
+	seed        maphash.Seed
+	keyIsInt    bool // Fast path flag for int keys
+	keyIsInt64  bool // Fast path flag for int64 keys
+	keyIsString bool // Fast path flag for string keys
 }
 
 // shard is an independent S3-FIFO cache partition.
@@ -95,6 +96,8 @@ func newS3FIFO[K comparable, V any](capacity int) *s3fifo[K, V] {
 		c.keyIsInt = true
 	case int64:
 		c.keyIsInt64 = true
+	case string:
+		c.keyIsString = true
 	}
 
 	for i := range numShards {
@@ -133,7 +136,7 @@ func newShard[K comparable, V any](capacity int) *shard[K, V] {
 
 // getShard returns the shard for a given key using type-optimized hashing.
 // Uses bitwise AND with shardMask for fast modulo (numShards must be power of 2).
-// Fast paths for int and int64 keys avoid the type switch overhead entirely.
+// Fast paths for int, int64, and string keys avoid the type switch overhead entirely.
 func (c *s3fifo[K, V]) getShard(key K) *shard[K, V] {
 	// Fast path for int keys (most common case in benchmarks).
 	// The keyIsInt flag is set once at construction, so this branch is predictable.
@@ -147,6 +150,12 @@ func (c *s3fifo[K, V]) getShard(key K) *shard[K, V] {
 		k := *(*int64)(unsafe.Pointer(&key))
 		return c.shards[uint64(k)&shardMask] //nolint:gosec // G115: intentional wrap
 	}
+	if c.keyIsString {
+		// Use unsafe to extract the string without boxing to any.
+		// This is safe because we only enter this path when K is string.
+		k := *(*string)(unsafe.Pointer(&key))
+		return c.shards[maphash.String(c.seed, k)&shardMask]
+	}
 	// Slow path: use type switch for other key types
 	return c.shards[c.shardIndexSlow(key)]
 }