add MemoryStats structure for monitoring

Author: Thomas Stromberg

README.md

@@ -103,3 +103,27 @@ fido has been hyper-tuned for high performance, and deviates from the original p
 ## License
 
 Apache 2.0
+
+### Memory diagnostics
+
+`Cache.MemoryStats` and `TieredCache.MemoryStats` sample the memory tier:
+
+```go
+stats, ok := cache.MemoryStats(func(key string, value []byte) uint64 {
+    return uint64(len(key) + cap(value))
+})
+if ok {
+    log.Printf("entries=%d capacity=%d pending=%d estimated_bytes=%d",
+        stats.Entries, stats.Capacity, stats.PendingEntries, stats.Bytes())
+}
+```
+
+The callback estimates referenced storage beyond the inline key/value headers.
+Use `nil` for structural accounting only. Sampling includes expired entries and
+entries pending eviction because they still retain memory. It takes O(N) time;
+run it periodically and retain the last sample when `ok` is false (writer busy).
+The full scan and callback run without the FIFO writer lock. Counts and bytes
+are approximate under concurrent changes, and shared backing storage may be
+counted more than once. Estimates exclude allocator rounding, xsync map/lock
+internals, in-flight loads and process overhead. Use Go heap profiles for an
+independent measurement. This method never contacts a persistent Store.

stats.go

@@ -0,0 +1,85 @@
+package fido
+
+import "unsafe"
+
+// MemoryStats describes retained memory, including expired entries and entries
+// awaiting eviction. Counts and bytes are estimates during concurrent updates.
+// Bytes excludes allocator rounding, goroutine stacks, in-flight loads, and the
+// internal allocations of xsync maps and locks. It is not process RSS.
+type MemoryStats struct {
+	Entries         int
+	Capacity        int
+	PendingEntries  int
+	RetainedEntries int
+	StructuralBytes uint64
+	PayloadBytes    uint64
+}
+
+// Bytes returns the estimated bytes accounted for by this snapshot.
+func (s MemoryStats) Bytes() uint64 { return s.StructuralBytes + s.PayloadBytes }
+
+// MemoryStats samples the cache without waiting for its writer lock. False
+// means the cache is busy; retain the previous sample and retry later. With a
+// non-nil sizeOf it takes O(N) time and should run periodically, not per request.
+// sizeOf reports referenced key/value storage beyond their inline Go headers;
+// for string keys and []byte values this is len(key)+cap(value). It must be fast,
+// must not mutate the cache or its values. Shared backing storage
+// can be counted multiple times. A nil sizeOf reports only structural bytes.
+func (c *Cache[K, V]) MemoryStats(sizeOf func(K, V) uint64) (MemoryStats, bool) {
+	return c.memory.memoryStats(sizeOf)
+}
+
+// MemoryStats samples only the memory tier. Persistent storage is owned by
+// Store and is deliberately not scanned or contacted by this method.
+func (c *TieredCache[K, V]) MemoryStats(sizeOf func(K, V) uint64) (MemoryStats, bool) {
+	return c.memory.memoryStats(sizeOf)
+}
+
+func (c *s3fifo[K, V]) memoryStats(sizeOf func(K, V) uint64) (MemoryStats, bool) {
+	var s MemoryStats
+	var recycledKey K
+	var recycledValue V
+	var recycled bool
+	// Only queue metadata needs the writer lock. Traverse the concurrent map
+	// and call user code after releasing it, like Range; diagnostics must not
+	// stop insertions for the duration of a full-cache scan.
+	if !func() bool {
+		if !c.mu.TryLock() {
+			return false
+		}
+		defer c.mu.Unlock()
+		s = MemoryStats{Entries: c.len(), Capacity: c.capacity, RetainedEntries: c.entries.Size()}
+		for _, e := range c.deathRow {
+			if e != nil {
+				s.PendingEntries++
+			}
+		}
+		var e entry[K, V]
+		s.StructuralBytes = uint64(unsafe.Sizeof(*c)) + 2*uint64(unsafe.Sizeof(bloomFilter{})) +
+			uint64(cap(c.ghostActive.data)+cap(c.ghostAging.data))*8 +
+			uint64(cap(c.deathRow))*uint64(unsafe.Sizeof(&e)) +
+			uint64(s.RetainedEntries)*uint64(unsafe.Sizeof(e))
+		if c.freeEntry != nil {
+			s.StructuralBytes += uint64(unsafe.Sizeof(e))
+			if sizeOf != nil {
+				recycledKey = c.freeEntry.key
+				recycledValue, recycled = c.freeEntry.loadValue()
+			}
+		}
+		return true
+	}() {
+		return MemoryStats{}, false
+	}
+	if sizeOf != nil {
+		c.entries.Range(func(k K, e *entry[K, V]) bool {
+			if v, ok := e.loadValue(); ok {
+				s.PayloadBytes += sizeOf(k, v)
+			}
+			return true
+		})
+		if recycled {
+			s.PayloadBytes += sizeOf(recycledKey, recycledValue)
+		}
+	}
+	return s, true
+}

stats_test.go

@@ -0,0 +1,72 @@
+package fido
+
+import "testing"
+
+func TestMemoryStats(t *testing.T) {
+	c := New[string, []byte](Size(8))
+	sizeOf := func(k string, v []byte) uint64 { return uint64(len(k) + cap(v)) }
+	c.Set("abc", make([]byte, 2, 10))
+	st, ok := c.MemoryStats(sizeOf)
+	if !ok || st.Entries != 1 || st.RetainedEntries != 1 || st.Capacity != 8 || st.PayloadBytes != 13 || st.StructuralBytes == 0 {
+		t.Fatalf("unexpected stats: %+v, %v", st, ok)
+	}
+	c.memory.mu.Lock()
+	_, ok = c.MemoryStats(sizeOf)
+	c.memory.mu.Unlock()
+	if ok {
+		t.Fatal("snapshot should report busy without waiting")
+	}
+	c.Delete("abc")
+	st, ok = c.MemoryStats(sizeOf)
+	if !ok || st.Entries != 0 || st.PayloadBytes != 0 {
+		t.Fatalf("deleted payload retained: %+v", st)
+	}
+	c.Set("expired", make([]byte, 5))
+	e, _ := c.memory.getEntry("expired")
+	e.expirySec.Store(1)
+	st, ok = c.MemoryStats(sizeOf)
+	if !ok || st.PayloadBytes != 12 {
+		t.Fatalf("expired storage not counted: %+v", st)
+	}
+}
+
+func TestMemoryStatsPendingEviction(t *testing.T) {
+	c := New[string, []byte](Size(8))
+	c.Set("a", make([]byte, 10))
+	e, _ := c.memory.getEntry("a")
+	e.setFreqPeak(0, 1)
+	c.memory.small.remove(e)
+	c.memory.sendToDeathRow(e)
+	st, ok := c.MemoryStats(func(k string, v []byte) uint64 { return uint64(len(k) + cap(v)) })
+	if !ok || st.Entries != 0 || st.PendingEntries != 1 || st.RetainedEntries != 1 || st.PayloadBytes != 11 {
+		t.Fatalf("pending storage not counted: %+v", st)
+	}
+}
+
+func TestMemoryStatsSizerDoesNotHoldWriterLock(t *testing.T) {
+	c := New[int, int](Size(8))
+	c.Set(1, 2)
+	_, ok := c.MemoryStats(func(int, int) uint64 {
+		if !c.memory.mu.TryLock() {
+			t.Fatal("sizer runs under writer lock")
+		}
+		c.memory.mu.Unlock()
+		return 1
+	})
+	if !ok {
+		t.Fatal("unexpected busy cache")
+	}
+}
+
+func BenchmarkMemoryStats128K(b *testing.B) {
+	c := New[int, []byte](Size(128000))
+	for i := 0; i < 128000; i++ {
+		c.Set(i, make([]byte, 256))
+	}
+	sizeOf := func(_ int, v []byte) uint64 { return uint64(cap(v)) }
+	b.ReportAllocs()
+	b.ResetTimer()
+	for b.Loop() {
+		c.MemoryStats(sizeOf)
+	}
+}