offheap 0.1.0

package/src/algorithms/tinylfu.rs

@@ -0,0 +1,499 @@
+use std::collections::HashMap;
+use super::{CacheImpl, CacheEntry, CacheStats};
+
+// Count-Min Sketch with 4-bit counters and aging.
+// Sized dynamically relative to cache capacity.
+struct FrequencySketch {
+    table: Vec<u8>,
+    mask: usize,
+    sample_size: usize,
+    additions: usize,
+}
+
+impl FrequencySketch {
+    fn new(capacity: usize) -> Self {
+        // Number of counters: next power of 2 of capacity * 4, min 128
+        let counters = (capacity * 4).next_power_of_two().max(128);
+        let bytes = counters / 2;
+        Self {
+            table: vec![0; bytes],
+            mask: counters - 1,
+            sample_size: (capacity * 10).max(1024),
+            additions: 0,
+        }
+    }
+
+    fn increment(&mut self, key: &str) {
+        let hash = seahash::hash(key.as_bytes());
+        let h1 = (hash & 0xFFFFFFFF) as usize;
+        let h2 = (hash >> 32) as usize;
+
+        let mut added = false;
+        for i in 0..4 {
+            let idx = (h1.wrapping_add(i * h2)) & self.mask;
+            if self.increment_at(idx) {
+                added = true;
+            }
+        }
+
+        if added {
+            self.additions += 1;
+            if self.additions >= self.sample_size {
+                self.decay();
+            }
+        }
+    }
+
+    fn increment_at(&mut self, idx: usize) -> bool {
+        let byte_idx = idx / 2;
+        let is_high = idx % 2 == 1;
+        let val = self.table[byte_idx];
+
+        if is_high {
+            let count = val >> 4;
+            if count < 15 {
+                self.table[byte_idx] = (val & 0x0F) | ((count + 1) << 4);
+                return true;
+            }
+        } else {
+            let count = val & 0x0F;
+            if count < 15 {
+                self.table[byte_idx] = (val & 0xF0) | (count + 1);
+                return true;
+            }
+        }
+        false
+    }
+
+    fn estimate(&self, key: &str) -> u8 {
+        let hash = seahash::hash(key.as_bytes());
+        let h1 = (hash & 0xFFFFFFFF) as usize;
+        let h2 = (hash >> 32) as usize;
+
+        let mut min_val = 15;
+        for i in 0..4 {
+            let idx = (h1.wrapping_add(i * h2)) & self.mask;
+            let val = self.counter_at(idx);
+            if val < min_val {
+                min_val = val;
+            }
+        }
+        min_val
+    }
+
+    fn counter_at(&self, idx: usize) -> u8 {
+        let byte_idx = idx / 2;
+        let is_high = idx % 2 == 1;
+        let val = self.table[byte_idx];
+        if is_high {
+            val >> 4
+        } else {
+            val & 0x0F
+        }
+    }
+
+    fn decay(&mut self) {
+        for val in self.table.iter_mut() {
+            let high = (*val >> 4) >> 1;
+            let low = (*val & 0x0F) >> 1;
+            *val = (high << 4) | low;
+        }
+        self.additions = 0;
+    }
+}
+
+#[derive(Copy, Clone, PartialEq, Debug)]
+enum TinyLfuList {
+    Window,
+    Probation,
+    Protected,
+}
+
+struct TinyLfuNode {
+    key: String,
+    entry: CacheEntry,
+    list: TinyLfuList,
+    prev: Option<usize>,
+    next: Option<usize>,
+}
+
+struct TinyLfuListMetadata {
+    head: Option<usize>,
+    tail: Option<usize>,
+    len: usize,
+    capacity: usize,
+}
+
+impl TinyLfuListMetadata {
+    fn new(capacity: usize) -> Self {
+        Self {
+            head: None,
+            tail: None,
+            len: 0,
+            capacity,
+        }
+    }
+}
+
+pub struct TinyLfuCache {
+    capacity: usize,
+    map: HashMap<String, usize>,
+    nodes: Vec<TinyLfuNode>,
+    free_nodes: Vec<usize>,
+
+    window: TinyLfuListMetadata,
+    probation: TinyLfuListMetadata,
+    protected: TinyLfuListMetadata,
+
+    sketch: FrequencySketch,
+    hits: u64,
+    misses: u64,
+}
+
+impl TinyLfuCache {
+    pub fn new(capacity: usize) -> Self {
+        // Segment capacities:
+        // Window: 1% (min 1)
+        // Main: 99%
+        //   Probation: 20% of Main (min 1 if Main capacity > 0)
+        //   Protected: 80% of Main
+        let window_cap = (capacity / 100).max(1);
+        let main_cap = capacity.saturating_sub(window_cap);
+
+        let (probation_cap, protected_cap) = if main_cap > 0 {
+            let prob = (main_cap * 20 / 100).max(1);
+            let prot = main_cap.saturating_sub(prob);
+            (prob, prot)
+        } else {
+            (0, 0)
+        };
+
+        Self {
+            capacity,
+            map: HashMap::with_capacity(capacity),
+            nodes: Vec::with_capacity(capacity),
+            free_nodes: Vec::new(),
+            window: TinyLfuListMetadata::new(window_cap),
+            probation: TinyLfuListMetadata::new(probation_cap),
+            protected: TinyLfuListMetadata::new(protected_cap),
+            sketch: FrequencySketch::new(capacity),
+            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 {
+            TinyLfuList::Window => &mut self.window,
+            TinyLfuList::Probation => &mut self.probation,
+            TinyLfuList::Protected => &mut self.protected,
+        };
+
+        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: TinyLfuList) {
+        self.nodes[idx].list = list;
+        let meta = match list {
+            TinyLfuList::Window => &mut self.window,
+            TinyLfuList::Probation => &mut self.probation,
+            TinyLfuList::Protected => &mut self.protected,
+        };
+
+        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].entry = CacheEntry::new(Vec::new(), None);
+        key
+    }
+}
+
+impl CacheImpl for TinyLfuCache {
+    fn get(&mut self, key: &str) -> Option<Vec<u8>> {
+        self.sketch.increment(key);
+
+        if let Some(&idx) = self.map.get(key) {
+            if self.nodes[idx].entry.is_expired() {
+                self.remove_completely(idx);
+                self.map.remove(key);
+                self.misses += 1;
+                None
+            } else {
+                let list = self.nodes[idx].list;
+                match list {
+                    TinyLfuList::Window => {
+                        self.detach(idx);
+                        self.attach_to_head(idx, TinyLfuList::Window);
+                    }
+                    TinyLfuList::Probation => {
+                        // Promote to Protected segment
+                        self.detach(idx);
+                        self.attach_to_head(idx, TinyLfuList::Protected);
+
+                        // Handle potential overflow of Protected segment
+                        if self.protected.len > self.protected.capacity {
+                            if let Some(prot_tail) = self.protected.tail {
+                                self.detach(prot_tail);
+                                self.attach_to_head(prot_tail, TinyLfuList::Probation);
+                            }
+                        }
+                    }
+                    TinyLfuList::Protected => {
+                        self.detach(idx);
+                        self.attach_to_head(idx, TinyLfuList::Protected);
+                    }
+                }
+                self.hits += 1;
+                Some(self.nodes[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>> {
+        self.sketch.increment(key);
+
+        if let Some(&idx) = self.map.get(key) {
+            // Key exists. Update value.
+            let old_value = std::mem::replace(
+                &mut self.nodes[idx].entry,
+                CacheEntry::new(value, ttl_ms),
+            ).value;
+
+            // Perform promotion/MRU updates identical to `get`
+            let list = self.nodes[idx].list;
+            match list {
+                TinyLfuList::Window => {
+                    self.detach(idx);
+                    self.attach_to_head(idx, TinyLfuList::Window);
+                }
+                TinyLfuList::Probation => {
+                    self.detach(idx);
+                    self.attach_to_head(idx, TinyLfuList::Protected);
+
+                    if self.protected.len > self.protected.capacity {
+                        if let Some(prot_tail) = self.protected.tail {
+                            self.detach(prot_tail);
+                            self.attach_to_head(prot_tail, TinyLfuList::Probation);
+                        }
+                    }
+                }
+                TinyLfuList::Protected => {
+                    self.detach(idx);
+                    self.attach_to_head(idx, TinyLfuList::Protected);
+                }
+            }
+            Some(old_value)
+        } else {
+            // Check if we have capacity at all
+            if self.capacity == 0 {
+                return None;
+            }
+
+            // Create new node inside Window segment
+            let new_idx = if let Some(free_idx) = self.free_nodes.pop() {
+                self.nodes[free_idx].key = key.to_string();
+                self.nodes[free_idx].entry = CacheEntry::new(value, ttl_ms);
+                free_idx
+            } else {
+                let free_idx = self.nodes.len();
+                self.nodes.push(TinyLfuNode {
+                    key: key.to_string(),
+                    entry: CacheEntry::new(value, ttl_ms),
+                    list: TinyLfuList::Window,
+                    prev: None,
+                    next: None,
+                });
+                free_idx
+            };
+
+            self.attach_to_head(new_idx, TinyLfuList::Window);
+            self.map.insert(key.to_string(), new_idx);
+
+            // If Window segment overflows
+            if self.window.len > self.window.capacity {
+                if let Some(win_tail) = self.window.tail {
+                    // Candidate to move to Main cache (Probation segment)
+                    let candidate_idx = win_tail;
+                    self.detach(candidate_idx);
+
+                    let main_has_capacity = self.probation.capacity > 0;
+                    if main_has_capacity {
+                        let total_size = self.window.len + self.probation.len + self.protected.len;
+                        if total_size + 1 <= self.capacity {
+                            // Cache is not full yet. Admit candidate directly.
+                            self.attach_to_head(candidate_idx, TinyLfuList::Probation);
+                        } else {
+                            // Cache is full. Compare candidate and victim.
+                            if let Some(prob_tail) = self.probation.tail {
+                                let victim_idx = prob_tail;
+
+                                let candidate_key = &self.nodes[candidate_idx].key;
+                                let victim_key = &self.nodes[victim_idx].key;
+
+                                let candidate_freq = self.sketch.estimate(candidate_key);
+                                let victim_freq = self.sketch.estimate(victim_key);
+
+                                if candidate_freq > victim_freq {
+                                    // Candidate wins! Evict victim, admit candidate.
+                                    let evicted_key = self.remove_completely(victim_idx);
+                                    self.map.remove(&evicted_key);
+                                    self.attach_to_head(candidate_idx, TinyLfuList::Probation);
+                                } else {
+                                    // Candidate loses! Evict candidate, keep victim.
+                                    let evicted_key = self.remove_completely(candidate_idx);
+                                    self.map.remove(&evicted_key);
+                                }
+                            } else {
+                                // Fallback if no victim (should not happen if len == capacity > 0)
+                                self.attach_to_head(candidate_idx, TinyLfuList::Probation);
+                            }
+                        }
+                    } else {
+                        // Main Cache capacity is 0 (capacity == 1 edge case).
+                        // Candidate is evicted directly.
+                        let evicted_key = self.remove_completely(candidate_idx);
+                        self.map.remove(&evicted_key);
+                    }
+                }
+            }
+            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.window.head = None;
+        self.window.tail = None;
+        self.window.len = 0;
+        self.probation.head = None;
+        self.probation.tail = None;
+        self.probation.len = 0;
+        self.protected.head = None;
+        self.protected.tail = None;
+        self.protected.len = 0;
+        self.hits = 0;
+        self.misses = 0;
+        // FrequencySketch is not cleared completely, but can be decay'd or just left as is.
+        // Actually, clearing table is cleaner:
+        self.sketch.table.fill(0);
+        self.sketch.additions = 0;
+    }
+
+    fn stats(&self) -> CacheStats {
+        CacheStats {
+            hits: self.hits,
+            misses: self.misses,
+            capacity: self.capacity,
+            size: self.window.len + self.probation.len + self.protected.len,
+        }
+    }
+
+    fn keys(&self) -> Vec<String> {
+        let mut result = Vec::new();
+        // Return window keys
+        let mut curr = self.window.head;
+        while let Some(idx) = curr {
+            let node = &self.nodes[idx];
+            if !node.entry.is_expired() {
+                result.push(node.key.clone());
+            }
+            curr = node.next;
+        }
+        // Return probation keys
+        let mut curr = self.probation.head;
+        while let Some(idx) = curr {
+            let node = &self.nodes[idx];
+            if !node.entry.is_expired() {
+                result.push(node.key.clone());
+            }
+            curr = node.next;
+        }
+        // Return protected keys
+        let mut curr = self.protected.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_tinylfu_basic() {
+        let mut cache = TinyLfuCache::new(5);
+        
+        // Fill cache
+        for i in 0..5 {
+            cache.set(&format!("key-{}", i), vec![i], None);
+        }
+        assert_eq!(cache.stats().size, 5);
+
+        // Increase frequency of key-0 and key-1
+        for _ in 0..3 {
+            cache.get("key-0");
+            cache.get("key-1");
+        }
+
+        // Add a new key. TinyLFU will compare frequency of candidate vs probation victim.
+        // It will evict a low-frequency key.
+        cache.set("key-5", vec![5], None);
+        
+        // key-0 and key-1 must remain because of high frequency.
+        assert!(cache.get("key-0").is_some());
+        assert!(cache.get("key-1").is_some());
+    }
+}

package/src/cache.rs

@@ -0,0 +1,172 @@
+use std::sync::Arc;
+use napi::{Env, JsUnknown, JsBuffer, JsString, Result, ValueType};
+use super::algorithms::{CacheImpl, CacheStats, lru::LruCache, arc::ArcCache, tinylfu::TinyLfuCache};
+
+#[napi(object)]
+pub struct CacheConfig {
+    pub policy: String,
+    pub capacity: u32,
+}
+
+#[napi(object)]
+pub struct CacheStatsJs {
+    pub hits: f64,
+    pub misses: f64,
+    pub capacity: f64,
+    pub size: f64,
+}
+
+#[napi]
+pub struct Cache {
+    inner: Arc<parking_lot::Mutex<Box<dyn CacheImpl>>>,
+}
+
+impl Clone for Cache {
+    fn clone(&self) -> Self {
+        Self {
+            inner: Arc::clone(&self.inner),
+        }
+    }
+}
+
+impl Cache {
+    pub fn from_config(config: CacheConfig) -> Self {
+        let capacity = config.capacity as usize;
+        let policy_lower = config.policy.to_lowercase();
+        let inner: Box<dyn CacheImpl> = match policy_lower.as_str() {
+            "arc" => Box::new(ArcCache::new(capacity)),
+            "tinylfu" | "w-tinylfu" => Box::new(TinyLfuCache::new(capacity)),
+            _ => Box::new(LruCache::new(capacity)),
+        };
+        Self {
+            inner: Arc::new(parking_lot::Mutex::new(inner)),
+        }
+    }
+}
+
+#[napi]
+impl Cache {
+    #[napi]
+    pub fn get(&self, env: Env, key: String) -> Result<JsUnknown> {
+        let mut lock = self.inner.lock();
+        if let Some(bytes) = lock.get(&key) {
+            if bytes.is_empty() {
+                return Ok(env.get_undefined()?.into_unknown());
+            }
+            let tag = bytes[0];
+            let payload = &bytes[1..];
+            match tag {
+                1 => {
+                    // Buffer
+                    let js_buf = env.create_buffer_copy(payload)?;
+                    Ok(js_buf.into_unknown())
+                }
+                2 => {
+                    // String
+                    let s = std::str::from_utf8(payload)
+                        .map_err(|e| napi::Error::new(napi::Status::StringExpected, e.to_string()))?;
+                    let js_str = env.create_string(s)?;
+                    Ok(js_str.into_unknown())
+                }
+                3 => {
+                    // JSON
+                    let json_val: serde_json::Value = serde_json::from_slice(payload)
+                        .map_err(|e| napi::Error::new(napi::Status::InvalidArg, e.to_string()))?;
+                    let parsed = env.to_js_value(&json_val)?;
+                    Ok(parsed)
+                }
+                _ => Err(napi::Error::new(napi::Status::InvalidArg, "Invalid data type tag in cache storage")),
+            }
+        } else {
+            Ok(env.get_undefined()?.into_unknown())
+        }
+    }
+
+    #[napi]
+    pub fn set(&self, env: Env, key: String, value: JsUnknown, ttl_ms: Option<f64>) -> Result<JsUnknown> {
+        let mut bytes = Vec::new();
+        let value_type = value.get_type()?;
+
+        if value.is_buffer()? {
+            let buf = JsBuffer::try_from(value)?;
+            let raw_bytes: Vec<u8> = buf.into_value()?.to_vec();
+            bytes.push(1); // Tag: Buffer
+            bytes.extend_from_slice(&raw_bytes);
+        } else if value_type == ValueType::String {
+            let js_str = JsString::try_from(value)?;
+            let utf8 = js_str.into_utf8()?;
+            bytes.push(2); // Tag: String
+            bytes.extend_from_slice(utf8.as_slice());
+        } else {
+            // Treat as JSON
+            let json_val: serde_json::Value = env.from_js_value(value)?;
+            let serialized = serde_json::to_vec(&json_val)
+                .map_err(|e| napi::Error::new(napi::Status::InvalidArg, e.to_string()))?;
+            bytes.push(3); // Tag: JSON
+            bytes.extend_from_slice(&serialized);
+        }
+
+        let ttl = ttl_ms.map(|ms| ms as u64);
+        let mut lock = self.inner.lock();
+        let old_bytes = lock.set(&key, bytes, ttl);
+
+        if let Some(bytes) = old_bytes {
+            if bytes.is_empty() {
+                return Ok(env.get_undefined()?.into_unknown());
+            }
+            let tag = bytes[0];
+            let payload = &bytes[1..];
+            match tag {
+                1 => {
+                    let js_buf = env.create_buffer_copy(payload)?;
+                    Ok(js_buf.into_unknown())
+                }
+                2 => {
+                    let s = std::str::from_utf8(payload)
+                        .map_err(|e| napi::Error::new(napi::Status::StringExpected, e.to_string()))?;
+                    let js_str = env.create_string(s)?;
+                    Ok(js_str.into_unknown())
+                }
+                3 => {
+                    let json_val: serde_json::Value = serde_json::from_slice(payload)
+                        .map_err(|e| napi::Error::new(napi::Status::InvalidArg, e.to_string()))?;
+                    let parsed = env.to_js_value(&json_val)?;
+                    Ok(parsed)
+                }
+                _ => Err(napi::Error::new(napi::Status::InvalidArg, "Invalid data type tag in cache storage")),
+            }
+        } else {
+            Ok(env.get_undefined()?.into_unknown())
+        }
+    }
+
+    #[napi]
+    pub fn delete(&self, key: String) -> bool {
+        let mut lock = self.inner.lock();
+        lock.delete(&key)
+    }
+
+    #[napi]
+    pub fn clear(&self) {
+        let mut lock = self.inner.lock();
+        lock.clear();
+    }
+
+    #[napi]
+    pub fn stats(&self) -> CacheStatsJs {
+        let lock = self.inner.lock();
+        let stats = lock.stats();
+        CacheStatsJs {
+            hits: stats.hits as f64,
+            misses: stats.misses as f64,
+            capacity: stats.capacity as f64,
+            size: stats.size as f64,
+        }
+    }
+
+    #[napi]
+    pub fn keys(&self) -> Vec<String> {
+        let lock = self.inner.lock();
+        lock.keys()
+    }
+}

package/src/lib.rs

@@ -0,0 +1,6 @@
+#[macro_use]
+extern crate napi_derive;
+
+pub mod algorithms;
+pub mod cache;
+pub mod manager;