Add FIFO cache implementation with metrics support

- Introduced a FIFO cache that evicts the oldest items when capacity is reached, providing predictable eviction behavior.
- Implemented two versions: one with metrics tracking and another without, allowing for flexible usage based on feature flags.
- Added comprehensive documentation detailing architecture, eviction flow, and performance characteristics.
- Included tests for core operations and stale entry handling to ensure reliability and correctness of the cache behavior.

Author: TKorr

src/policy/fifo.rs src/policy/fifo/fifo_metrics.rssrc/policy/fifo.rs renamed to src/policy/fifo/fifo_metrics.rs

@@ -260,7 +260,7 @@
 //! ## Thread Safety
 //!
 //! - `FIFOCache` is **NOT thread-safe**
-//! - Wrap in `Arc<RwLock<FIFOCache>>` for concurrent access
+//! - Use `ConcurrentFIFOCache` for thread-safe access
 //! - Designed for single-threaded use with external synchronization
 //! - Follows Rust's zero-cost abstractions principle
 //!
@@ -273,7 +273,8 @@
 
 use crate::metrics::metrics_impl::CacheMetrics;
 use crate::metrics::snapshot::CacheMetricsSnapshot;
-use crate::traits::{CoreCache, FIFOCacheTrait};
+use crate::traits::{ConcurrentCache, CoreCache, FIFOCacheTrait};
+use parking_lot::RwLock;
 use std::collections::{HashMap, VecDeque, hash_map};
 use std::fmt::Debug;
 use std::hash::Hash;
@@ -427,6 +428,101 @@ where
     }
 }
 
+/// Thread-safe FIFO cache wrapper using RwLock.
+#[derive(Clone, Debug)]
+pub struct ConcurrentFIFOCache<K, V>
+where
+    K: Eq + Hash,
+{
+    inner: Arc<RwLock<FIFOCache<K, V>>>,
+}
+
+impl<K, V> ConcurrentFIFOCache<K, V>
+where
+    K: Eq + Hash + Debug,
+    V: Debug,
+{
+    pub fn new(capacity: usize) -> Self {
+        Self {
+            inner: Arc::new(RwLock::new(FIFOCache::new(capacity))),
+        }
+    }
+
+    pub fn insert(&self, key: K, value: V) -> Option<V> {
+        let mut cache = self.inner.write();
+        cache.insert(key, value)
+    }
+
+    pub fn get(&self, key: &K) -> Option<V>
+    where
+        V: Clone,
+    {
+        let mut cache = self.inner.write();
+        cache.get(key).cloned()
+    }
+
+    pub fn contains(&self, key: &K) -> bool {
+        let cache = self.inner.read();
+        cache.contains(key)
+    }
+
+    pub fn len(&self) -> usize {
+        let cache = self.inner.read();
+        cache.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        let cache = self.inner.read();
+        cache.is_empty()
+    }
+
+    pub fn capacity(&self) -> usize {
+        let cache = self.inner.read();
+        cache.capacity()
+    }
+
+    pub fn clear(&self) {
+        let mut cache = self.inner.write();
+        cache.clear();
+    }
+
+    pub fn pop_oldest(&self) -> Option<(K, V)> {
+        let mut cache = self.inner.write();
+        cache.pop_oldest()
+    }
+
+    pub fn peek_oldest(&self) -> Option<(K, V)>
+    where
+        K: Clone,
+        V: Clone,
+    {
+        let cache = self.inner.read();
+        cache.peek_oldest().map(|(k, v)| (k.clone(), v.clone()))
+    }
+
+    pub fn pop_oldest_batch(&self, count: usize) -> Vec<(K, V)> {
+        let mut cache = self.inner.write();
+        cache.pop_oldest_batch(count)
+    }
+
+    pub fn age_rank(&self, key: &K) -> Option<usize> {
+        let cache = self.inner.read();
+        cache.age_rank(key)
+    }
+
+    pub fn metrics_snapshot(&self) -> CacheMetricsSnapshot {
+        let cache = self.inner.read();
+        cache.metrics_snapshot()
+    }
+}
+
+impl<K, V> ConcurrentCache for ConcurrentFIFOCache<K, V>
+where
+    K: Eq + Hash + Debug + Send + Sync,
+    V: Debug + Send + Sync,
+{
+}
+
 impl<K, V> CoreCache<K, V> for FIFOCache<K, V>
 where
     K: Eq + Hash,