Merge pull request #2

Add TTL support and refactor store architecture

Author: mehrantsi

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "feoxdb"
-version = "0.1.3"
+version = "0.2.0"
 edition = "2021"
 authors = ["Mehran Toosi <dev@mehran.dk>"]
 description = "Iron-oxide fast embedded database - nanosecond-level key-value storage"

README.md

@@ -135,12 +135,38 @@ fn main() -> feoxdb::Result<()> {
         .max_memory(2_000_000_000)  // 2GB limit
         .enable_caching(true)        // Enable CLOCK cache
         .hash_bits(20)               // 1M hash buckets
+        .enable_ttl(true)            // Enable TTL support
         .build()?;
 
     Ok(())
 }
 ```
 
+### Time-To-Live (TTL) Support
+
+```rust
+use feoxdb::FeoxStore;
+
+// Enable TTL feature via builder
+let store = FeoxStore::builder()
+    .enable_ttl(true)
+    .build()?;
+
+// Set key to expire after 60 seconds
+store.insert_with_ttl(b"session:123", b"session_data", 60)?;
+
+// Check remaining TTL
+if let Some(ttl) = store.get_ttl(b"session:123")? {
+    println!("Session expires in {} seconds", ttl);
+}
+
+// Extend TTL to 120 seconds
+store.update_ttl(b"session:123", 120)?;
+
+// Remove TTL (make permanent)
+store.persist(b"session:123")?;
+```
+
 ### Concurrent Access
 
 ```rust

src/core/mod.rs

@@ -1,3 +1,4 @@
 pub mod cache;
 pub mod record;
 pub mod store;
+pub mod ttl_sweep;

src/core/record.rs

@@ -8,25 +8,24 @@ use crate::constants::*;
 #[repr(C)]
 #[derive(Debug)]
 pub struct Record {
-    // Hash table link for intrusive list
-    pub hash_link: AtomicLink,
-
-    // Key and value data
-    pub key: Vec<u8>,
-    pub key_len: u16,
-    pub value: parking_lot::RwLock<Option<Bytes>>, // None when value is on disk
-    pub value_len: usize,
-
-    // Metadata
-    pub timestamp: u64,
-    pub sector: AtomicU64, // Disk sector location (0 means in-memory only)
-
-    // Reference counting for RCU-style access
-    pub refcount: AtomicU32,
-
-    // Cache metadata
-    pub cache_ref_bit: AtomicU32,
-    pub cache_access_time: AtomicU64,
+    // Cache line 1 (64 bytes) - GET hot path
+    // These 3 fields are accessed together on EVERY GET operation
+    pub key: Vec<u8>,                              // 24 bytes
+    pub value: parking_lot::RwLock<Option<Bytes>>, // ~40 bytes (32 + Option overhead)
+
+    // Cache line 2 (64 bytes) - TTL and metadata
+    pub ttl_expiry: AtomicU64, // 8 bytes - checked on every GET
+    pub timestamp: u64,        // 8 bytes - checked on updates
+    pub value_len: usize,      // 8 bytes - used for size calcs
+    pub sector: AtomicU64,     // 8 bytes - for persistence
+    pub refcount: AtomicU32,   // 4 bytes - memory management
+    pub key_len: u16,          // 2 bytes - used with value_len
+    // Total so far: 40 bytes
+
+    // Still in cache line 2 or start of line 3 - cold fields
+    pub hash_link: AtomicLink,        // 8 bytes - only for hash ops
+    pub cache_ref_bit: AtomicU32,     // 4 bytes - rarely used
+    pub cache_access_time: AtomicU64, // 8 bytes - rarely used
 }
 
 // Custom atomic link for lock-free hash table
@@ -91,14 +90,20 @@ impl Record {
         let value_bytes = Bytes::from(value);
 
         Self {
-            hash_link: AtomicLink::new(),
-            key_len,
+            // Cache line 1 - GET hot path
             key,
             value: parking_lot::RwLock::new(Some(value_bytes)),
-            value_len,
+
+            // Cache line 2 - TTL and metadata
+            ttl_expiry: AtomicU64::new(0),
             timestamp,
+            value_len,
             sector: AtomicU64::new(0),
             refcount: AtomicU32::new(1),
+            key_len,
+
+            // Cold fields
+            hash_link: AtomicLink::new(),
             cache_ref_bit: AtomicU32::new(0),
             cache_access_time: AtomicU64::new(0),
         }
@@ -108,6 +113,17 @@ impl Record {
         Self::new(key, value, timestamp)
     }
 
+    pub fn new_with_timestamp_ttl(
+        key: Vec<u8>,
+        value: Vec<u8>,
+        timestamp: u64,
+        ttl_expiry: u64,
+    ) -> Self {
+        let record = Self::new(key, value, timestamp);
+        record.ttl_expiry.store(ttl_expiry, Ordering::Release);
+        record
+    }
+
     pub fn calculate_size(&self) -> usize {
         mem::size_of::<Self>() + self.key.capacity() + self.value_len
     }