Crate sine_cache

This library provides a powerful in-memory caching solution with support for customizable eviction policies and persistence using Append-Only Files (AOF). It allows efficient management of key-value pairs, ensuring both performance optimization and data persistence across application lifecycles.

Features

• Multiple Eviction Policies: Choose from FIFO (First-In, First-Out), LRU (Least Recently Used), and LFU (Least Frequently Used) eviction policies to suit different data access patterns.

• Customizable Eviction Strategies: Implement custom eviction policies by defining types that adhere to the EvictionPolicy trait, allowing tailored cache management.

• Asynchronous Support: AsyncCache struct provides async methods for operations like get, put, and remove, ensuring efficient handling of concurrent requests in async-await contexts.

• Persistence with Append-Only Files (AOF): Optionally persist cache state across restarts using AOF, ensuring data integrity and recovery after crashes.

• Thread Safety: AsyncCache utilizes tokio::sync::Mutex to manage concurrent access safely, making it suitable for multi-threaded environments.

• Efficient Memory Management: Optimizes memory usage with smart pointers and references, reducing redundancy and improving overall performance.

• Configuration Flexibility: Configure cache size limits, eviction policies, and persistence settings through intuitive configuration structs (CacheSyncConfig and AsyncCacheConfig).

• Detailed Documentation: Comprehensive API documentation and examples facilitate easy integration and usage within applications.

• Safety and Reliability: Built with Rust’s strong type system and ownership model, ensuring memory safety and preventing common bugs like null pointer dereferencing and data races.

Examples

Cache - Synchronous Cache:

use sine_cache::{cache::Cache, config::CacheConfig};

fn main() {
    let capacity = 10; // Maximum number of entries in the cache.
    let mut cache = Cache::new(sine_cache::config::CacheSyncConfig::LFU(CacheConfig{max_size: capacity}));

    // Inserting key-value pairs into the cache
    cache.put(1, "One");
    cache.put(1, "one"); // Overwrites previous value
    cache.put(2, "Two");

    // Retrieving a value from the cache
    let value = cache.get(&1);
    assert!(value.is_some_and(|x| x == &"one"));
}

AsyncCache - Asynchronous Cache:

• Without AOF:

use sine_cache::{cache::AsyncCache, config::{AsyncCacheConfig, EvictionAsyncConfig}};

#[tokio::main]
async fn main() {
    let capacity = 10; // Maximum number of entries in the cache.
    let mut cache = AsyncCache::new(AsyncCacheConfig::LFU(EvictionAsyncConfig {max_size: capacity, aof_config: None})).await;

    // Inserting key-value pairs into the cache
    cache.put(1, String::from("One")).await;
    cache.put(1, String::from("one")).await; // Overwrites previous value
    cache.put(2, String::from("Two")).await;

    // Retrieving a value from the cache
    let value = cache.get(&1).await;
    assert!(value.is_some_and(|x| x == "one"));
}

• With AOF:

use sine_cache::{cache::AsyncCache, config::{AsyncCacheConfig, EvictionAsyncConfig, EvictionAOFConfig}};

#[tokio::main]
async fn main() {
     
    let capacity = 10; // Maximum number of entries in the cache.
    let mut cache = AsyncCache::new(AsyncCacheConfig::LFU(EvictionAsyncConfig {
        max_size: capacity,
        aof_config: Some(EvictionAOFConfig {
            folder: String::from("./data"), //folder in which persistent file should be written.
            cache_name: String::from("async_lof_cache"), //Unique cache name as with same name file will be created.
            flush_time: Some(5000) //After every 5000 milliseconds data will be flushed to disk.
        })
    })).await;

    // Inserting key-value pairs into the cache
    cache.put(1, String::from("One")).await;
    cache.put(1, String::from("one")).await; // Overwrites previous value
    cache.put(2, String::from("Two")).await;

    // Retrieving a value from the cache
    let value = cache.get(&1).await;
    assert!(value.is_some_and(|x| x == "one"));
}

Custom eviction policy

use sine_cache::eviction_policies::common::EvictionPolicy;
use sine_cache::{cache::AsyncCache, config::{AsyncCacheConfig, CustomEvictionAsyncConfig, CustomEvictionAOFConfig}};
 
pub struct CustomEviction<K> {
    _phantom: std::marker::PhantomData<K>,
}
impl<K: Eq + std::hash::Hash + Clone> CustomEviction<K> {
    pub fn new() -> Self{
        Self{
            _phantom: std::marker::PhantomData
        }
    }
}
 
impl<K: Eq + std::hash::Hash + Clone> EvictionPolicy<K> for CustomEviction<K> {
    fn on_get(&mut self, key: &K) {
        // nothing to do.
    }
 
    fn on_set(&mut self, key: K) {
        // nothing to do.
    }
 
    fn evict(&mut self) -> Option<K> {
        // nothing to do
        None
    }
 
    fn remove(&mut self, key: K) {
        //nothing to do
    }
}
 
#[tokio::main]
async fn main() {
     
    let capacity = 10; // Maximum number of entries in the cache.
    let mut cache = AsyncCache::new(AsyncCacheConfig::Custom(CustomEvictionAsyncConfig {
        max_size: capacity,
        aof_config: Some(CustomEvictionAOFConfig {
            folder: String::from("./data"), //folder in which persistent file should be written.
            cache_name: String::from("async_lof_custom_cache"), //Unique cache name as with same name file will be created.
            flush_time: Some(5000), //After every 5000 milliseconds data will be flushed to disk.
            persist_read_ops: true //whether to store reads also, true generally.
        }),
        policy: Box::new(CustomEviction::new())
    })).await;

    // Inserting key-value pairs into the cache
    cache.put(1, String::from("One")).await;
    cache.put(1, String::from("one")).await; // Overwrites previous value
    cache.put(2, String::from("Two")).await;

    // Retrieving a value from the cache
    let value = cache.get(&1).await;
    assert!(value.is_some_and(|x| x == "one"));
}
 

For detailed API documentation and further customization options, refer to the library’s documentation. For more examples, go through test modules on github library

Modules

aof

Contains code for AOF for persisting data.

cache

Code of Cache and AsyncCache struct which provides functionalities of caching.

cache_events

Contains logic what to do when some event take place in ThreadSafeCache.

common

Contains common structs and traits used throughout the library.

config

Contains code to define different configurations to use Cache and AsyncCache

eviction_policies

This module provides various eviction policies that can be used with a cache implementation. An eviction policy defines the strategy for removing entries from a cache when it reaches its capacity. Different eviction policies prioritize different criteria for eviction, such as least recently used (LRU) or first-in-first-out (FIFO) or Least Frequently Used(LFU).