plain_cache/lib.rs
1//! A highly performant, thread-safe cache implementation.
2//!
3//! This crate provides a cache that implements the S3-FIFO eviction algorithm as specified in
4//! [FIFO Queues are All You Need for Cache Eviction](https://dl.acm.org/doi/pdf/10.1145/3600006.3613147).
5//!
6//! # Features
7//!
8//! - Thread-safe by default - no need for explicit synchronization
9//! - S3-FIFO eviction algorithm for optimal cache performance
10//! - Sharded design to reduce contention during concurrent access
11//! - No unsafe code
12//!
13//! # Safety
14//!
15//! This crate is designed to be safe and easy to use:
16//!
17//! - No unsafe code is used
18//! - Thread-safe by default when wrapped in `Arc`
19//! - All operations are atomic
20//!
21//! # Examples
22//!
23//! Basic usage with string keys and values:
24//!
25//! ```rust
26//! use plain_cache::Cache;
27//!
28//! // Create a new cache with a capacity of 1000 items
29//! let cache = Cache::with_capacity(1000);
30//!
31//! // Insert and retrieve a value
32//! cache.insert("key1", "value1");
33//! assert_eq!(cache.get("key1"), Some("value1"));
34//! ```
35//!
36//! Updating existing values:
37//!
38//! ```rust
39//! use plain_cache::Cache;
40//!
41//! let cache = Cache::with_capacity(100);
42//!
43//! // Insert initial value
44//! cache.insert("key1", "value1");
45//!
46//! // Update the value and get the old one
47//! let old_value = cache.insert("key1", "new_value");
48//! assert_eq!(old_value, Some("value1"));
49//! assert_eq!(cache.get("key1"), Some("new_value"));
50//! ```
51//!
52//! Thread-safe usage across multiple threads:
53//!
54//! ```rust
55//! use plain_cache::Cache;
56//! use std::sync::Arc;
57//! use std::thread;
58//!
59//! let cache = Arc::new(Cache::with_capacity(100));
60//! cache.insert("key1", "value1");
61//!
62//! // Spawn a thread that inserts a value
63//! let cache_in_arc = Arc::clone(&cache);
64//! let handle = thread::spawn(move || {
65//! cache_in_arc.insert("key2", "value2");
66//! });
67//!
68//! handle.join().unwrap();
69//!
70//! assert_eq!(cache.get("key1"), Some("value1"));
71//! assert_eq!(cache.get("key2"), Some("value2"));
72//! ```
73
74#![forbid(unsafe_code)]
75pub mod cache;
76
77pub use cache::Cache;