micro optimizations

Author: Thomas Stromberg

README.md

@@ -1,5 +1,7 @@
 # bdcache - Big Dumb Cache
 
+<img src="media/logo-small.png" alt="bdcache logo" width="256" align="right">
+
 [![Go Reference](https://pkg.go.dev/badge/github.com/codeGROOVE-dev/bdcache.svg)](https://pkg.go.dev/github.com/codeGROOVE-dev/bdcache)
 [![Go Report Card](https://goreportcard.com/badge/github.com/codeGROOVE-dev/bdcache)](https://goreportcard.com/report/github.com/codeGROOVE-dev/bdcache)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
@@ -10,7 +12,6 @@ Simple, fast, secure Go cache with [S3-FIFO eviction](https://s3fifo.com/) - bet
 
 - **S3-FIFO Algorithm** - [Superior cache hit rates](https://s3fifo.com/) compared to LRU/LFU
 - **Fast** - ~20ns per operation, zero allocations
-- **Secure** - Hardened input validation, no path traversal
 - **Reliable** - Memory cache always works, even if persistence fails
 - **Smart Persistence** - Local files for dev, Cloud Datastore for Cloud Run
 - **Minimal Dependencies** - Only one (Cloud Datastore)
@@ -48,9 +49,17 @@ cache, err := bdcache.New[string, User](ctx, bdcache.WithBestStore("myapp"))
 
 ## Performance
 
+Benchmarks from MacBook Pro M4 Max:
+
 ```
-BenchmarkCache_Get_Hit-16      63M ops/sec    19.9 ns/op    0 allocs
-BenchmarkCache_Set-16          57M ops/sec    20.8 ns/op    0 allocs
+Memory-only operations:
+BenchmarkCache_Get_Hit-16      56M ops/sec    17.8 ns/op       0 B/op     0 allocs
+BenchmarkCache_Set-16          56M ops/sec    17.8 ns/op       0 B/op     0 allocs
+
+With file persistence enabled:
+BenchmarkCache_Get_PersistMemoryHit-16    85M ops/sec    11.8 ns/op       0 B/op     0 allocs
+BenchmarkCache_Get_PersistDiskRead-16     73K ops/sec    13.8 µs/op    7921 B/op   178 allocs
+BenchmarkCache_Set_WithPersistence-16      9K ops/sec   112.3 µs/op    2383 B/op    36 allocs
 ```
 
 ## License

cache_test.go

@@ -772,7 +772,7 @@ func BenchmarkCache_Set_WithPersistence(b *testing.B) {
 	}
 }
 
-func BenchmarkCache_Get_WithPersistence(b *testing.B) {
+func BenchmarkCache_Get_PersistMemoryHit(b *testing.B) {
 	ctx := context.Background()
 	cacheID := "bench-persist-get-" + time.Now().Format("20060102150405")
 	cache, err := New[int, int](ctx, WithLocalStore(cacheID))
@@ -785,7 +785,7 @@ func BenchmarkCache_Get_WithPersistence(b *testing.B) {
 		}
 	}()
 
-	// Populate cache
+	// Populate cache with keys 0-999
 	for i := range 1000 {
 		if err := cache.Set(ctx, i, i, 0); err != nil {
 			b.Fatalf("Set: %v", err)
@@ -794,7 +794,43 @@ func BenchmarkCache_Get_WithPersistence(b *testing.B) {
 
 	b.ResetTimer()
 	for i := range b.N {
-		// Most hits from memory, occasional disk miss
-		_, _, _ = cache.Get(ctx, i%10000) //nolint:errcheck // Benchmark code
+		// All hits from memory (keys 0-999)
+		_, _, _ = cache.Get(ctx, i%1000) //nolint:errcheck // Benchmark code
+	}
+}
+
+func BenchmarkCache_Get_PersistDiskRead(b *testing.B) {
+	ctx := context.Background()
+	cacheID := "bench-persist-disk-" + time.Now().Format("20060102150405")
+
+	// Create cache with small memory capacity to force disk reads
+	cache, err := New[int, int](ctx, WithLocalStore(cacheID), WithMemorySize(10))
+	if err != nil {
+		b.Fatalf("New: %v", err)
+	}
+	defer func() {
+		if err := cache.Close(); err != nil {
+			b.Logf("Close error: %v", err)
+		}
+	}()
+
+	// Populate cache with 100 items (memory only holds 10)
+	for i := range 100 {
+		if err := cache.Set(ctx, i, i, 0); err != nil {
+			b.Fatalf("Set: %v", err)
+		}
+	}
+
+	// Force eviction of first 90 items from memory
+	for i := 100; i < 110; i++ {
+		if err := cache.Set(ctx, i, i, 0); err != nil {
+			b.Fatalf("Set: %v", err)
+		}
+	}
+
+	b.ResetTimer()
+	for i := range b.N {
+		// Read evicted items from disk (keys 0-89)
+		_, _, _ = cache.Get(ctx, i%90) //nolint:errcheck // Benchmark code
 	}
 }

persist_file.go

@@ -1,6 +1,7 @@
 package bdcache
 
 import (
+	"bufio"
 	"context"
 	"encoding/gob"
 	"errors"
@@ -10,14 +11,32 @@ import (
 	"path/filepath"
 	"sort"
 	"strings"
+	"sync"
 	"time"
 )
 
 const maxKeyLength = 127 // Maximum key length to avoid filesystem constraints
 
+var (
+	// Pool for bufio.Writer to reduce allocations
+	writerPool = sync.Pool{
+		New: func() any {
+			return bufio.NewWriterSize(nil, 4096)
+		},
+	}
+	// Pool for bufio.Reader to reduce allocations
+	readerPool = sync.Pool{
+		New: func() any {
+			return bufio.NewReaderSize(nil, 4096)
+		},
+	}
+)
+
 // filePersist implements PersistenceLayer using local files with gob encoding.
 type filePersist[K comparable, V any] struct {
-	dir string
+	dir          string
+	subdirsMu    sync.RWMutex
+	subdirsMade  map[string]bool // Cache of created subdirectories
 }
 
 // ValidateKey checks if a key is valid for file persistence.
@@ -69,7 +88,10 @@ func newFilePersist[K comparable, V any](cacheID string) (*filePersist[K, V], er
 
 	slog.Debug("initialized file persistence", "dir", dir)
 
-	return &filePersist[K, V]{dir: dir}, nil
+	return &filePersist[K, V]{
+		dir:         dir,
+		subdirsMade: make(map[string]bool),
+	}, nil
 }
 
 // keyToFilename converts a cache key to a filename with squid-style directory layout.
@@ -105,8 +127,13 @@ func (f *filePersist[K, V]) Load(ctx context.Context, key K) (V, time.Time, bool
 		}
 	}()
 
+	// Get reader from pool and reset it for this file
+	reader := readerPool.Get().(*bufio.Reader)
+	reader.Reset(file)
+	defer readerPool.Put(reader)
+
 	var entry Entry[K, V]
-	dec := gob.NewDecoder(file)
+	dec := gob.NewDecoder(reader)
 	if err := dec.Decode(&entry); err != nil {
 		// File corrupted, remove it
 		if err := os.Remove(filename); err != nil && !os.IsNotExist(err) {
@@ -129,10 +156,22 @@ func (f *filePersist[K, V]) Load(ctx context.Context, key K) (V, time.Time, bool
 // Store saves a value to a file.
 func (f *filePersist[K, V]) Store(ctx context.Context, key K, value V, expiry time.Time) error {
 	filename := filepath.Join(f.dir, f.keyToFilename(key))
+	subdir := filepath.Dir(filename)
+
+	// Check if subdirectory already created (cache to avoid syscalls)
+	f.subdirsMu.RLock()
+	exists := f.subdirsMade[subdir]
+	f.subdirsMu.RUnlock()
 
-	// Create subdirectory if it doesn't exist (for squid-style layout)
-	if err := os.MkdirAll(filepath.Dir(filename), 0o750); err != nil {
-		return fmt.Errorf("create subdirectory: %w", err)
+	if !exists {
+		// Create subdirectory if needed
+		if err := os.MkdirAll(subdir, 0o750); err != nil {
+			return fmt.Errorf("create subdirectory: %w", err)
+		}
+		// Cache that we created it
+		f.subdirsMu.Lock()
+		f.subdirsMade[subdir] = true
+		f.subdirsMu.Unlock()
 	}
 
 	entry := Entry[K, V]{
@@ -149,8 +188,19 @@ func (f *filePersist[K, V]) Store(ctx context.Context, key K, value V, expiry ti
 		return fmt.Errorf("create temp file: %w", err)
 	}
 
-	enc := gob.NewEncoder(file)
+	// Get writer from pool and reset it for this file
+	writer := writerPool.Get().(*bufio.Writer)
+	writer.Reset(file)
+
+	enc := gob.NewEncoder(writer)
 	encErr := enc.Encode(entry)
+	if encErr == nil {
+		encErr = writer.Flush() // Ensure buffered data is written
+	}
+
+	// Return writer to pool
+	writerPool.Put(writer)
+
 	closeErr := file.Close()
 
 	if encErr != nil {
@@ -227,10 +277,15 @@ func (f *filePersist[K, V]) LoadRecent(ctx context.Context, limit int) (<-chan E
 				return nil
 			}
 
+			// Get reader from pool and reset it for this file
+			reader := readerPool.Get().(*bufio.Reader)
+			reader.Reset(file)
+
 			var e Entry[K, V]
-			dec := gob.NewDecoder(file)
+			dec := gob.NewDecoder(reader)
 			if err := dec.Decode(&e); err != nil {
 				slog.Warn("failed to decode cache file", "file", path, "error", err)
+				readerPool.Put(reader)
 				if err := file.Close(); err != nil {
 					slog.Debug("failed to close file after decode error", "file", path, "error", err)
 				}
@@ -239,6 +294,7 @@ func (f *filePersist[K, V]) LoadRecent(ctx context.Context, limit int) (<-chan E
 				}
 				return nil
 			}
+			readerPool.Put(reader)
 			if err := file.Close(); err != nil {
 				slog.Debug("failed to close file", "file", path, "error", err)
 			}

s3fifo.go

@@ -60,24 +60,26 @@ func newS3FIFO[K comparable, V any](capacity int) *s3fifo[K, V] {
 // get retrieves a value from the cache.
 func (c *s3fifo[K, V]) get(key K) (V, bool) {
 	c.mu.Lock()
-	defer c.mu.Unlock()
-
 	ent, ok := c.items[key]
 	if !ok {
+		c.mu.Unlock()
 		var zero V
 		return zero, false
 	}
 
-	// Check expiration
+	// Check expiration (skip time.Now() if no expiry set)
 	if !ent.expiry.IsZero() && time.Now().After(ent.expiry) {
+		c.mu.Unlock()
 		var zero V
 		return zero, false
 	}
 
 	// Increment frequency counter (used during eviction)
 	ent.freq++
+	val := ent.value
+	c.mu.Unlock()
 
-	return ent.value, true
+	return val, true
 }
 
 // set adds or updates a value in the cache.