offheap 0.1.0

package/src/algorithms/arc.rs

@@ -0,0 +1,355 @@
+use std::collections::HashMap;
+use super::{CacheImpl, CacheEntry, CacheStats};
+
+#[derive(Copy, Clone, PartialEq, Debug)]
+enum ArcList {
+    T1,
+    B1,
+    T2,
+    B2,
+}
+
+struct ArcNode {
+    key: String,
+    value: Option<CacheEntry>, // Only T1 and T2 store values. B1 and B2 are ghost entries.
+    list: ArcList,
+    prev: Option<usize>,
+    next: Option<usize>,
+}
+
+struct ArcListMetadata {
+    head: Option<usize>,
+    tail: Option<usize>,
+    len: usize,
+}
+
+impl ArcListMetadata {
+    fn new() -> Self {
+        Self {
+            head: None,
+            tail: None,
+            len: 0,
+        }
+    }
+}
+
+pub struct ArcCache {
+    capacity: usize,
+    map: HashMap<String, usize>,
+    nodes: Vec<ArcNode>,
+    free_nodes: Vec<usize>,
+    
+    t1: ArcListMetadata,
+    b1: ArcListMetadata,
+    t2: ArcListMetadata,
+    b2: ArcListMetadata,
+    
+    p: usize, // Target size for T1
+    hits: u64,
+    misses: u64,
+}
+
+impl ArcCache {
+    pub fn new(capacity: usize) -> Self {
+        Self {
+            capacity,
+            map: HashMap::with_capacity(capacity * 2), // Map contains history as well
+            nodes: Vec::with_capacity(capacity * 2),
+            free_nodes: Vec::new(),
+            t1: ArcListMetadata::new(),
+            b1: ArcListMetadata::new(),
+            t2: ArcListMetadata::new(),
+            b2: ArcListMetadata::new(),
+            p: 0,
+            hits: 0,
+            misses: 0,
+        }
+    }
+
+    fn detach(&mut self, idx: usize) {
+        let prev = self.nodes[idx].prev;
+        let next = self.nodes[idx].next;
+        let list = self.nodes[idx].list;
+
+        let meta = match list {
+            ArcList::T1 => &mut self.t1,
+            ArcList::B1 => &mut self.b1,
+            ArcList::T2 => &mut self.t2,
+            ArcList::B2 => &mut self.b2,
+        };
+
+        if let Some(p) = prev {
+            self.nodes[p].next = next;
+        } else {
+            meta.head = next;
+        }
+
+        if let Some(n) = next {
+            self.nodes[n].prev = prev;
+        } else {
+            meta.tail = prev;
+        }
+
+        meta.len -= 1;
+        self.nodes[idx].prev = None;
+        self.nodes[idx].next = None;
+    }
+
+    fn attach_to_head(&mut self, idx: usize, list: ArcList) {
+        self.nodes[idx].list = list;
+        let meta = match list {
+            ArcList::T1 => &mut self.t1,
+            ArcList::B1 => &mut self.b1,
+            ArcList::T2 => &mut self.t2,
+            ArcList::B2 => &mut self.b2,
+        };
+
+        self.nodes[idx].prev = None;
+        self.nodes[idx].next = meta.head;
+
+        if let Some(h) = meta.head {
+            self.nodes[h].prev = Some(idx);
+        } else {
+            meta.tail = Some(idx);
+        }
+
+        meta.head = Some(idx);
+        meta.len += 1;
+    }
+
+    fn remove_completely(&mut self, idx: usize) -> String {
+        self.detach(idx);
+        self.free_nodes.push(idx);
+        let key = std::mem::take(&mut self.nodes[idx].key);
+        self.nodes[idx].value = None;
+        key
+    }
+
+    fn replace(&mut self, key_in_b2: bool) {
+        if self.t1.len > 0 && (self.t1.len > self.p || (key_in_b2 && self.t1.len == self.p)) {
+            if let Some(t1_tail) = self.t1.tail {
+                self.detach(t1_tail);
+                self.nodes[t1_tail].value = None; // Evict value from memory
+                self.attach_to_head(t1_tail, ArcList::B1);
+            }
+        } else {
+            if let Some(t2_tail) = self.t2.tail {
+                self.detach(t2_tail);
+                self.nodes[t2_tail].value = None; // Evict value from memory
+                self.attach_to_head(t2_tail, ArcList::B2);
+            }
+        }
+    }
+}
+
+impl CacheImpl for ArcCache {
+    fn get(&mut self, key: &str) -> Option<Vec<u8>> {
+        if let Some(&idx) = self.map.get(key) {
+            let list = self.nodes[idx].list;
+            match list {
+                ArcList::T1 | ArcList::T2 => {
+                    let expired = if let Some(ref entry) = self.nodes[idx].value {
+                        entry.is_expired()
+                    } else {
+                        true
+                    };
+
+                    if expired {
+                        self.remove_completely(idx);
+                        self.map.remove(key);
+                        self.misses += 1;
+                        None
+                    } else {
+                        self.detach(idx);
+                        self.attach_to_head(idx, ArcList::T2);
+                        self.hits += 1;
+                        self.nodes[idx].value.as_ref().map(|e| e.value.clone())
+                    }
+                }
+                ArcList::B1 | ArcList::B2 => {
+                    // History hit. We can't return value (evicted), so counts as miss for user,
+                    // but we trigger adaptation.
+                    self.misses += 1;
+                    None
+                }
+            }
+        } else {
+            self.misses += 1;
+            None
+        }
+    }
+
+    fn set(&mut self, key: &str, value: Vec<u8>, ttl_ms: Option<u64>) -> Option<Vec<u8>> {
+        if self.capacity == 0 {
+            return None;
+        }
+
+        if let Some(&idx) = self.map.get(key) {
+            let list = self.nodes[idx].list;
+            match list {
+                ArcList::T1 | ArcList::T2 => {
+                    // Cache hit. Update value.
+                    let old_value = self.nodes[idx].value.replace(CacheEntry::new(value, ttl_ms)).map(|e| e.value);
+                    self.detach(idx);
+                    self.attach_to_head(idx, ArcList::T2);
+                    old_value
+                }
+                ArcList::B1 => {
+                    // Hit in B1: we need more recency
+                    let b1_len = if self.b1.len == 0 { 1 } else { self.b1.len };
+                    let delta = std::cmp::max(1, self.b2.len / b1_len);
+                    self.p = std::cmp::min(self.p + delta, self.capacity);
+
+                    self.replace(false);
+
+                    self.detach(idx);
+                    self.nodes[idx].value = Some(CacheEntry::new(value, ttl_ms));
+                    self.attach_to_head(idx, ArcList::T2);
+                    None
+                }
+                ArcList::B2 => {
+                    // Hit in B2: we need more frequency
+                    let b2_len = if self.b2.len == 0 { 1 } else { self.b2.len };
+                    let delta = std::cmp::max(1, self.b1.len / b2_len);
+                    self.p = self.p.saturating_sub(delta);
+
+                    self.replace(true);
+
+                    self.detach(idx);
+                    self.nodes[idx].value = Some(CacheEntry::new(value, ttl_ms));
+                    self.attach_to_head(idx, ArcList::T2);
+                    None
+                }
+            }
+        } else {
+            // Cache Miss (not in cache, nor in history)
+            let l1_len = self.t1.len + self.b1.len;
+            let l2_len = self.t2.len + self.b2.len;
+
+            if l1_len == self.capacity {
+                if self.t1.len < self.capacity {
+                    if let Some(b1_tail) = self.b1.tail {
+                        let evicted_key = self.remove_completely(b1_tail);
+                        self.map.remove(&evicted_key);
+                    }
+                    self.replace(false);
+                } else {
+                    if let Some(t1_tail) = self.t1.tail {
+                        let evicted_key = self.remove_completely(t1_tail);
+                        self.map.remove(&evicted_key);
+                    }
+                }
+            } else if l1_len < self.capacity && l1_len + l2_len >= self.capacity {
+                if l1_len + l2_len == 2 * self.capacity {
+                    if let Some(b2_tail) = self.b2.tail {
+                        let evicted_key = self.remove_completely(b2_tail);
+                        self.map.remove(&evicted_key);
+                    }
+                }
+                self.replace(false);
+            }
+
+            // Create new node
+            let idx = if let Some(free_idx) = self.free_nodes.pop() {
+                self.nodes[free_idx].key = key.to_string();
+                self.nodes[free_idx].value = Some(CacheEntry::new(value, ttl_ms));
+                free_idx
+            } else {
+                let free_idx = self.nodes.len();
+                self.nodes.push(ArcNode {
+                    key: key.to_string(),
+                    value: Some(CacheEntry::new(value, ttl_ms)),
+                    list: ArcList::T1,
+                    prev: None,
+                    next: None,
+                });
+                free_idx
+            };
+
+            self.attach_to_head(idx, ArcList::T1);
+            self.map.insert(key.to_string(), idx);
+            None
+        }
+    }
+
+    fn delete(&mut self, key: &str) -> bool {
+        if let Some(&idx) = self.map.get(key) {
+            self.remove_completely(idx);
+            self.map.remove(key);
+            true
+        } else {
+            false
+        }
+    }
+
+    fn clear(&mut self) {
+        self.map.clear();
+        self.nodes.clear();
+        self.free_nodes.clear();
+        self.t1 = ArcListMetadata::new();
+        self.b1 = ArcListMetadata::new();
+        self.t2 = ArcListMetadata::new();
+        self.b2 = ArcListMetadata::new();
+        self.p = 0;
+        self.hits = 0;
+        self.misses = 0;
+    }
+
+    fn stats(&self) -> CacheStats {
+        CacheStats {
+            hits: self.hits,
+            misses: self.misses,
+            capacity: self.capacity,
+            size: self.t1.len + self.t2.len,
+        }
+    }
+
+    fn keys(&self) -> Vec<String> {
+        let mut result = Vec::new();
+        // Return active keys in T1
+        let mut curr = self.t1.head;
+        while let Some(idx) = curr {
+            let node = &self.nodes[idx];
+            let expired = node.value.as_ref().map_or(true, |e| e.is_expired());
+            if !expired {
+                result.push(node.key.clone());
+            }
+            curr = node.next;
+        }
+        // Return active keys in T2
+        let mut curr = self.t2.head;
+        while let Some(idx) = curr {
+            let node = &self.nodes[idx];
+            let expired = node.value.as_ref().map_or(true, |e| e.is_expired());
+            if !expired {
+                result.push(node.key.clone());
+            }
+            curr = node.next;
+        }
+        result
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_arc_basic() {
+        let mut cache = ArcCache::new(3);
+        cache.set("a", vec![1], None);
+        cache.set("b", vec![2], None);
+        cache.set("c", vec![3], None);
+        
+        // Hits to move to T2
+        assert_eq!(cache.get("a"), Some(vec![1]));
+        assert_eq!(cache.get("b"), Some(vec![2]));
+        
+        // Set new key, should evict c (which was in T1 and never hit)
+        cache.set("d", vec![4], None);
+        assert_eq!(cache.get("c"), None);
+        assert_eq!(cache.get("a"), Some(vec![1]));
+        assert_eq!(cache.get("b"), Some(vec![2]));
+        assert_eq!(cache.get("d"), Some(vec![4]));
+    }
+}

package/src/algorithms/lru.rs

@@ -0,0 +1,212 @@
+use std::collections::HashMap;
+use super::{CacheImpl, CacheEntry, CacheStats};
+
+struct LruNode {
+    key: String,
+    entry: CacheEntry,
+    prev: Option<usize>,
+    next: Option<usize>,
+}
+
+pub struct LruCache {
+    capacity: usize,
+    map: HashMap<String, usize>,
+    nodes: Vec<LruNode>,
+    free_nodes: Vec<usize>,
+    head: Option<usize>, // Most Recently Used
+    tail: Option<usize>, // Least Recently Used
+    hits: u64,
+    misses: u64,
+}
+
+impl LruCache {
+    pub fn new(capacity: usize) -> Self {
+        Self {
+            capacity,
+            map: HashMap::with_capacity(capacity),
+            nodes: Vec::with_capacity(capacity),
+            free_nodes: Vec::new(),
+            head: None,
+            tail: None,
+            hits: 0,
+            misses: 0,
+        }
+    }
+
+    fn detach(&mut self, node_idx: usize) {
+        let prev = self.nodes[node_idx].prev;
+        let next = self.nodes[node_idx].next;
+
+        if let Some(p) = prev {
+            self.nodes[p].next = next;
+        } else {
+            self.head = next;
+        }
+
+        if let Some(n) = next {
+            self.nodes[n].prev = prev;
+        } else {
+            self.tail = prev;
+        }
+
+        self.nodes[node_idx].prev = None;
+        self.nodes[node_idx].next = None;
+    }
+
+    fn attach_to_head(&mut self, node_idx: usize) {
+        self.nodes[node_idx].prev = None;
+        self.nodes[node_idx].next = self.head;
+
+        if let Some(h) = self.head {
+            self.nodes[h].prev = Some(node_idx);
+        } else {
+            self.tail = Some(node_idx);
+        }
+
+        self.head = Some(node_idx);
+    }
+
+    fn move_to_head(&mut self, node_idx: usize) {
+        if self.head == Some(node_idx) {
+            return;
+        }
+        self.detach(node_idx);
+        self.attach_to_head(node_idx);
+    }
+
+    fn remove_node(&mut self, node_idx: usize) -> (String, CacheEntry) {
+        self.detach(node_idx);
+        self.free_nodes.push(node_idx);
+        let key = std::mem::take(&mut self.nodes[node_idx].key);
+        let entry = std::mem::replace(&mut self.nodes[node_idx].entry, CacheEntry::new(Vec::new(), None));
+        (key, entry)
+    }
+}
+
+impl CacheImpl for LruCache {
+    fn get(&mut self, key: &str) -> Option<Vec<u8>> {
+        if let Some(&node_idx) = self.map.get(key) {
+            if self.nodes[node_idx].entry.is_expired() {
+                self.remove_node(node_idx);
+                self.map.remove(key);
+                self.misses += 1;
+                None
+            } else {
+                self.move_to_head(node_idx);
+                self.hits += 1;
+                Some(self.nodes[node_idx].entry.value.clone())
+            }
+        } else {
+            self.misses += 1;
+            None
+        }
+    }
+
+    fn set(&mut self, key: &str, value: Vec<u8>, ttl_ms: Option<u64>) -> Option<Vec<u8>> {
+        if let Some(&node_idx) = self.map.get(key) {
+            // Key exists, update it
+            let old_value = std::mem::replace(
+                &mut self.nodes[node_idx].entry,
+                CacheEntry::new(value, ttl_ms),
+            ).value;
+            self.move_to_head(node_idx);
+            Some(old_value)
+        } else {
+            // If full, evict the LRU (tail)
+            if self.map.len() >= self.capacity && self.capacity > 0 {
+                if let Some(t_idx) = self.tail {
+                    let (evicted_key, _) = self.remove_node(t_idx);
+                    self.map.remove(&evicted_key);
+                }
+            }
+
+            // Insert new entry
+            let node_idx = if let Some(idx) = self.free_nodes.pop() {
+                self.nodes[idx].key = key.to_string();
+                self.nodes[idx].entry = CacheEntry::new(value, ttl_ms);
+                idx
+            } else {
+                let idx = self.nodes.len();
+                self.nodes.push(LruNode {
+                    key: key.to_string(),
+                    entry: CacheEntry::new(value, ttl_ms),
+                    prev: None,
+                    next: None,
+                });
+                idx
+            };
+
+            self.attach_to_head(node_idx);
+            self.map.insert(key.to_string(), node_idx);
+            None
+        }
+    }
+
+    fn delete(&mut self, key: &str) -> bool {
+        if let Some(&node_idx) = self.map.get(key) {
+            self.remove_node(node_idx);
+            self.map.remove(key);
+            true
+        } else {
+            false
+        }
+    }
+
+    fn clear(&mut self) {
+        self.map.clear();
+        self.nodes.clear();
+        self.free_nodes.clear();
+        self.head = None;
+        self.tail = None;
+        self.hits = 0;
+        self.misses = 0;
+    }
+
+    fn stats(&self) -> CacheStats {
+        CacheStats {
+            hits: self.hits,
+            misses: self.misses,
+            capacity: self.capacity,
+            size: self.map.len(),
+        }
+    }
+
+    fn keys(&self) -> Vec<String> {
+        let mut result = Vec::new();
+        let mut curr = self.head;
+        while let Some(idx) = curr {
+            let node = &self.nodes[idx];
+            if !node.entry.is_expired() {
+                result.push(node.key.clone());
+            }
+            curr = node.next;
+        }
+        result
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_lru_basic() {
+        let mut cache = LruCache::new(2);
+        cache.set("a", vec![1], None);
+        cache.set("b", vec![2], None);
+        assert_eq!(cache.get("a"), Some(vec![1]));
+        cache.set("c", vec![3], None); // should evict "b"
+        assert_eq!(cache.get("b"), None);
+        assert_eq!(cache.get("a"), Some(vec![1]));
+        assert_eq!(cache.get("c"), Some(vec![3]));
+    }
+
+    #[test]
+    fn test_lru_expiry() {
+        let mut cache = LruCache::new(2);
+        cache.set("a", vec![1], Some(10)); // 10ms
+        assert_eq!(cache.get("a"), Some(vec![1]));
+        std::thread::sleep(std::time::Duration::from_millis(15));
+        assert_eq!(cache.get("a"), None);
+    }
+}

package/src/algorithms/mod.rs

@@ -0,0 +1,42 @@
+use std::time::{Duration, Instant};
+
+#[derive(Debug, Clone)]
+pub struct CacheStats {
+    pub hits: u64,
+    pub misses: u64,
+    pub capacity: usize,
+    pub size: usize,
+}
+
+pub struct CacheEntry {
+    pub value: Vec<u8>,
+    pub expires_at: Option<Instant>,
+}
+
+impl CacheEntry {
+    pub fn new(value: Vec<u8>, ttl_ms: Option<u64>) -> Self {
+        let expires_at = ttl_ms.map(|ms| Instant::now() + Duration::from_millis(ms));
+        Self { value, expires_at }
+    }
+
+    pub fn is_expired(&self) -> bool {
+        if let Some(expiry) = self.expires_at {
+            Instant::now() > expiry
+        } else {
+            false
+        }
+    }
+}
+
+pub trait CacheImpl: Send + Sync {
+    fn get(&mut self, key: &str) -> Option<Vec<u8>>;
+    fn set(&mut self, key: &str, value: Vec<u8>, ttl_ms: Option<u64>) -> Option<Vec<u8>>;
+    fn delete(&mut self, key: &str) -> bool;
+    fn clear(&mut self);
+    fn stats(&self) -> CacheStats;
+    fn keys(&self) -> Vec<String>;
+}
+
+pub mod lru;
+pub mod arc;
+pub mod tinylfu;