epoch_db/
lib.rs

1//! # EpochDB 🦀
2//!
3//! An intelligent, persistent, and concurrent key-value store for Rust,
4//! designed to manage data with a lifecycle.
5//!
6//! **EpochDB** is an opinionated database engine built on the robust foundation
7//! of `sled`. It's designed specifically for workloads where the relevance of
8//! data changes over time, such as caching, session management, and real-time
9//! analytics.
10//!
11//! It provides a high-level, ergonomic API by treating data's **access
12//! frequency** and **age** as first-class citizens.
13
14use std::path::PathBuf;
15use std::sync::Arc;
16use std::sync::atomic::AtomicBool;
17use std::thread::JoinHandle;
18
19use db::errors::TransientError;
20use serde::{
21    Deserialize,
22    Serialize
23};
24use sled::Tree;
25
26pub mod db;
27pub mod metadata;
28pub mod metrics;
29
30/// This is the main struct which represents the database.
31///
32/// This struct holds the connection to the `sled` database and provides
33/// safe, high-level access to the various data trees. It manages a background
34/// thread for handling TTL (Time-To-Live) expirations automatically.
35///
36/// When this struct is dropped, it will signal the background thread to shut
37/// down and wait for it to finish gracefully.
38///
39/// This struct also holds 2 Arc<sled::Tree> directly instead of a single
40/// sled::Db, since almost all of the functions uses the tree directly which
41/// requires the sled::Db to constantly open each trees.
42/// Passing trees from the struct deletes the constant need to open the trees
43#[derive(Debug)]
44pub struct DB {
45    /// Stores the key and value
46    data_tree: Arc<Tree>,
47    /// Stores the key and the metadata
48    meta_tree: Arc<Tree>,
49    /// Stores the ttl timestamp and the key
50    ttl_tree: Arc<Tree>,
51    /// Manage the background thread which checks for expired keys
52    ttl_thread: Option<JoinHandle<Result<(), TransientError>>>,
53    /// Manage the background thread to periodically check the DB Size
54    size_thread: Option<JoinHandle<Result<(), TransientError>>>,
55    /// Signals all threads to gracefully shutdown, when the DB is dropped
56    shutdown: Arc<AtomicBool>,
57    /// Path to the database
58    pub path: PathBuf
59}
60
61/// Contains additional information about a key, such as its access frequency
62/// and lifecycle.
63///
64/// NOTE: This struct derives Serialize and Deserialize to be stored as raw
65/// bytes (&[u8]) in the underlying sled tree.
66#[derive(Debug, Serialize, Deserialize, PartialEq)]
67pub struct Metadata {
68    /// The number of time the key has been accessed
69    pub freq: u64,
70    /// Timestamp of key creation, in seconds since the UNIX epoch
71    pub created_at: u64,
72    /// The key's time-to-live in seconds. If None, the key is persistent and
73    /// never expires.
74    pub ttl: Option<u64>
75}
epoch_db/lib.rs

epoch_db/
lib.rs
