Update metrics tracking and enhance cache eviction strategies

- Added metrics for bytes saved from cache to improve performance insights.
- Updated cache eviction strategies in MemoryFS and DiskFS to include metrics tracking for hits and evictions.
- Enhanced README.md with updated garbage collection algorithm descriptions and recommendations for cache usage.
- Introduced new madviseSequential functionality for improved memory access hints on Unix systems.
- Adjusted validation configuration in examples to better reflect realistic usage scenarios.

vfs/cache/cache.go

@@ -3,6 +3,7 @@ package cache
 
 import (
 	"io"
+	"s1d3sw1ped/steamcache2/steamcache/metrics"
 	"s1d3sw1ped/steamcache2/vfs"
 	"s1d3sw1ped/steamcache2/vfs/vfserror"
 	"sync/atomic"
@@ -10,8 +11,9 @@ import (
 
 // TieredCache implements a lock-free two-tier cache for better concurrency
 type TieredCache struct {
-	fast *atomic.Value // Memory cache (fast) - atomic.Value for lock-free access
-	slow *atomic.Value // Disk cache (slow) - atomic.Value for lock-free access
+	fast    *atomic.Value // Memory cache (fast) - atomic.Value for lock-free access
+	slow    *atomic.Value // Disk cache (slow) - atomic.Value for lock-free access
+	metrics *metrics.Metrics
 }
 
 // New creates a new tiered cache
@@ -22,6 +24,11 @@ func New() *TieredCache {
 	}
 }
 
+// SetMetrics allows wiring the top-level metrics collector (called from SteamCache).
+func (tc *TieredCache) SetMetrics(m *metrics.Metrics) {
+	tc.metrics = m
+}
+
 // SetFast sets the fast (memory) tier atomically
 func (tc *TieredCache) SetFast(vfs vfs.VFS) {
 	tc.fast.Store(vfs)
@@ -221,6 +228,10 @@ func (tc *TieredCache) promoteToFast(key string, reader io.ReadCloser) {
 				// Failure (e.g. mem pressure, concurrent evict) is non-fatal and does not affect correctness of slow tier.
 				_, _ = writer.Write(content)
 				_ = writer.Close()
+
+				if tc.metrics != nil {
+					tc.metrics.IncrementPromotions()
+				}
 			}
 		}
 	}