Struct Config 

pub struct Config {

    pub maxmemory: u64,
    pub eviction_policy: EvictionPolicy,
    pub data_dir: Option<PathBuf>,
    pub aof: bool,
    pub appendfsync: AppendFsync,
    pub snapshot_filename: String,
    pub aof_filename: String,
    pub ttl_reaper: TtlReaperMode,
    pub reaper_interval: Duration,
    pub reaper_samples: usize,
    pub reaper_max_rounds: u32,
    pub auto_aof_rewrite_pct: u32,
    pub auto_aof_rewrite_min_size: u64,
    pub shards: usize,
    /* private fields */
}

Embedded-store config. Build by chaining with_* methods on Config::default.

Fields

maxmemory: u64

Soft memory ceiling in bytes. 0 (default) = unlimited.

eviction_policy: EvictionPolicy

Eviction policy when over maxmemory. Default NoEviction.

data_dir: Option<PathBuf>

Persistence directory. None = pure in-memory (no AOF, no snapshot).

aof: bool

AOF on/off when data_dir is set. Defaults to true (on) when with_persist was called; ignored if data_dir is None.

appendfsync: AppendFsync

AOF fsync policy. Default EverySec (matches Redis: ≤ 1 s loss).

snapshot_filename: String

Snapshot file name inside data_dir (single-shard only; n > 1 always uses dump-{i}.rdb). Default "dump-0.rdb". A custom name opts the dir out of server interop: no shards.meta is recorded, and a kevy server opening the same dir won’t find the files.

aof_filename: String

AOF file name inside data_dir (single-shard only; n > 1 always uses aof-{i}.aof). Default "aof-0.aof". Same interop opt-out as Self::snapshot_filename.

ttl_reaper: TtlReaperMode

TTL reaper mode. Default Background.

reaper_interval: Duration

Reaper tick interval. Default 100 ms (10 Hz).

reaper_samples: usize

tick_expire samples per round. Default 20 (matches Redis).

reaper_max_rounds: u32

Max sample rounds per tick. Default 16.

auto_aof_rewrite_pct: u32

Auto-BGREWRITEAOF trigger: rewrite when the live AOF has grown by at least this percent over its size at the previous rewrite. 0 disables (call crate::Store::rewrite_aof manually). Default 100 (Redis).

auto_aof_rewrite_min_size: u64

Floor below which auto-rewrite is skipped. Default 64 MiB (Redis).

shards: usize

Keyspace shard count (hash(key) % shards), each a fully independent lock + keyspace + AOF (shared-nothing) — concurrent access scales across cores. Default 1 (single shard = the original single-lock / single-aof-0.aof layout, zero migration). Set > 1 via Self::with_shards; the first open with > 1 re-shards an existing single AOF into per-shard files.

Implementations

impl Config

pub fn with_persist(self, dir: impl Into<PathBuf>) -> Self

Enable persistence under dir — snapshot file + AOF land inside. AOF defaults on; turn it off with Self::without_aof for pure snapshot-only durability.

Examples found in repository

examples/replay_real_aof.rs (line 35)

fn main() {
    let path = std::env::args()
        .nth(1)
        .expect("usage: replay_real_aof <aof-path>");
    let src = PathBuf::from(&path);
    let bytes = std::fs::metadata(&src)
        .map(|m| m.len())
        .unwrap_or(0);
    println!("reproducer: staging {} bytes from {}", bytes, src.display());

    let dir = std::env::temp_dir().join(format!(
        "kevy-aof-reproducer-{}",
        std::process::id()
    ));
    std::fs::create_dir_all(&dir).expect("create temp dir");
    let staged = dir.join("aof-0.aof");
    std::fs::copy(&src, &staged).expect("copy AOF into staging dir");

    println!("reproducer: opening Store from {}", dir.display());
    let store = Store::open(
        Config::default()
            .with_persist(&dir)
            .with_aof_filename("aof-0.aof"),
    )
    .expect("Store::open");

    println!("reproducer: opened OK; dbsize = {}", store.dbsize());
}

examples/bench_embed.rs (line 63)

fn main() {
    let n: usize = std::env::var("KEVY_BENCH_N")
        .ok()
        .and_then(|s| s.parse().ok())
        .unwrap_or(2_000_000);
    // Keys precomputed outside the timed loop so `format!`/alloc cost isn't
    // attributed to kevy.
    let keys: Vec<Vec<u8>> = (0..KEYS).map(|i| format!("k{i}").into_bytes()).collect();

    println!("kevy-embedded in-process throughput — single thread, n={n}, {KEYS} keys, {}B val", VAL.len());

    let s1 = Store::open(Config::default().with_ttl_reaper_manual()).unwrap();
    bench("in-memory", &s1, n, &keys);

    let dir2 = std::env::temp_dir().join("kevy_embed_bench_everysec");
    let _ = std::fs::remove_dir_all(&dir2);
    let s2 = Store::open(
        Config::default()
            .with_persist(&dir2)
            .with_ttl_reaper_manual()
            .with_appendfsync(AppendFsync::EverySec),
    )
    .unwrap();
    bench("aof-everysec", &s2, n, &keys);

    let dir3 = std::env::temp_dir().join("kevy_embed_bench_always");
    let _ = std::fs::remove_dir_all(&dir3);
    let s3 = Store::open(
        Config::default()
            .with_persist(&dir3)
            .with_ttl_reaper_manual()
            .with_appendfsync(AppendFsync::Always),
    )
    .unwrap();
    // Always-fsync is one fdatasync per write (no group commit on the embedded
    // single-op path) — fsync-rate-bound, so run far fewer ops to stay bounded.
    bench("aof-always", &s3, (n / 20).max(50_000), &keys);

    // TTL'd-key GET: the mailrs path (every cache key has a TTL). With the
    // background reaper the cached clock is trusted (no per-get Instant::now);
    // manual mode reads a fresh clock per get — the gap is the cached-clock win.
    bench_ttl_get("ttl GET (cached clk)", false, n, &keys); // background reaper
    bench_ttl_get("ttl GET (fresh clk) ", true, n, &keys); // manual reaper

    drop((s1, s2, s3));
    let _ = std::fs::remove_dir_all(&dir2);
    let _ = std::fs::remove_dir_all(&dir3);
}

pub fn without_aof(self) -> Self

Disable the AOF (snapshot-only persistence — explicit save_snapshot calls are the only way data survives restart).

pub fn with_max_memory(self, bytes: u64) -> Self

Soft memory ceiling in bytes. 0 keeps the default (unlimited).

Examples found in repository

examples/embedded-cache.rs (line 12)

fn main() -> std::io::Result<()> {
    let s = Store::open(
        Config::default()
            .with_max_memory(200 * 1024)
            .with_eviction(EvictionPolicy::AllKeysLru),
    )?;

    for i in 0..10_000 {
        let key = format!("user:{i:05}");
        let val = format!("user-payload-{i}");
        s.set(key.as_bytes(), val.as_bytes())?;
    }

    println!("dbsize after insert flood: {}", s.dbsize());
    println!("used_memory: {} bytes (limit 200 KiB)", s.used_memory());
    println!("evictions_total: {}", s.evictions_total());

    // Touch a recent key — it should still be live.
    let recent = format!("user:0{}", 9999);
    println!(
        "user:09999 → {:?}",
        s.get(recent.as_bytes())?.as_deref().map(String::from_utf8_lossy)
    );

    Ok(())
}

pub fn with_eviction(self, policy: EvictionPolicy) -> Self

Eviction policy when over Self::with_max_memory.

Examples found in repository

examples/embedded-cache.rs (line 13)

fn main() -> std::io::Result<()> {
    let s = Store::open(
        Config::default()
            .with_max_memory(200 * 1024)
            .with_eviction(EvictionPolicy::AllKeysLru),
    )?;

    for i in 0..10_000 {
        let key = format!("user:{i:05}");
        let val = format!("user-payload-{i}");
        s.set(key.as_bytes(), val.as_bytes())?;
    }

    println!("dbsize after insert flood: {}", s.dbsize());
    println!("used_memory: {} bytes (limit 200 KiB)", s.used_memory());
    println!("evictions_total: {}", s.evictions_total());

    // Touch a recent key — it should still be live.
    let recent = format!("user:0{}", 9999);
    println!(
        "user:09999 → {:?}",
        s.get(recent.as_bytes())?.as_deref().map(String::from_utf8_lossy)
    );

    Ok(())
}

pub fn with_appendfsync(self, fsync: AppendFsync) -> Self

AOF fsync policy. Default AppendFsync::EverySec.

Examples found in repository

examples/bench_embed.rs (line 65)

fn main() {
    let n: usize = std::env::var("KEVY_BENCH_N")
        .ok()
        .and_then(|s| s.parse().ok())
        .unwrap_or(2_000_000);
    // Keys precomputed outside the timed loop so `format!`/alloc cost isn't
    // attributed to kevy.
    let keys: Vec<Vec<u8>> = (0..KEYS).map(|i| format!("k{i}").into_bytes()).collect();

    println!("kevy-embedded in-process throughput — single thread, n={n}, {KEYS} keys, {}B val", VAL.len());

    let s1 = Store::open(Config::default().with_ttl_reaper_manual()).unwrap();
    bench("in-memory", &s1, n, &keys);

    let dir2 = std::env::temp_dir().join("kevy_embed_bench_everysec");
    let _ = std::fs::remove_dir_all(&dir2);
    let s2 = Store::open(
        Config::default()
            .with_persist(&dir2)
            .with_ttl_reaper_manual()
            .with_appendfsync(AppendFsync::EverySec),
    )
    .unwrap();
    bench("aof-everysec", &s2, n, &keys);

    let dir3 = std::env::temp_dir().join("kevy_embed_bench_always");
    let _ = std::fs::remove_dir_all(&dir3);
    let s3 = Store::open(
        Config::default()
            .with_persist(&dir3)
            .with_ttl_reaper_manual()
            .with_appendfsync(AppendFsync::Always),
    )
    .unwrap();
    // Always-fsync is one fdatasync per write (no group commit on the embedded
    // single-op path) — fsync-rate-bound, so run far fewer ops to stay bounded.
    bench("aof-always", &s3, (n / 20).max(50_000), &keys);

    // TTL'd-key GET: the mailrs path (every cache key has a TTL). With the
    // background reaper the cached clock is trusted (no per-get Instant::now);
    // manual mode reads a fresh clock per get — the gap is the cached-clock win.
    bench_ttl_get("ttl GET (cached clk)", false, n, &keys); // background reaper
    bench_ttl_get("ttl GET (fresh clk) ", true, n, &keys); // manual reaper

    drop((s1, s2, s3));
    let _ = std::fs::remove_dir_all(&dir2);
    let _ = std::fs::remove_dir_all(&dir3);
}

pub fn with_auto_aof_rewrite(self, pct: u32, min_size: u64) -> Self

Auto-BGREWRITEAOF thresholds: rewrite once the AOF has grown pct percent past its size at the last rewrite AND is at least min_size bytes. In Background reaper mode the check runs on the reaper tick; in Manual mode it runs when you call crate::Store::tick. Pass pct = 0 to disable auto-rewrite (you can still call crate::Store::rewrite_aof yourself). Defaults: 100 % / 64 MiB.

pub fn with_shards(self, n: usize) -> Self

Shard the keyspace into n shared-nothing partitions (hash(key) % n), each with its own lock + keyspace + AOF, so concurrent access scales across cores. n clamps to ≥ 1; 1 (default) is the original single-shard layout. Going from a single-AOF store to n > 1 re-shards the existing aof-0.aof into aof-0..aof-{n-1} on the next open (the old file is backed up to aof-0.aof.premigration.<ts> first). Pub/sub is process-wide (handled on shard 0), not sharded.

Examples found in repository

examples/bench_embed_mt.rs (line 64)

fn main() {
    let n_per: usize = std::env::var("KEVY_BENCH_N")
        .ok()
        .and_then(|s| s.parse().ok())
        .unwrap_or(2_000_000);
    let keys: Vec<Vec<u8>> = (0..KEYS).map(|i| format!("k{i}").into_bytes()).collect();
    let shards: usize = std::env::var("KEVY_SHARDS")
        .ok()
        .and_then(|s| s.parse().ok())
        .unwrap_or(1);

    // Shared in-memory store (no AOF) — isolate the lock/keyspace from disk.
    let store = Store::open(Config::default().with_shards(shards).with_ttl_reaper_manual()).unwrap();
    for k in &keys {
        store.set(k, VAL).unwrap();
    }

    println!(
        "kevy-embedded MULTI-THREAD throughput — in-memory, shards={shards}, {KEYS} keys, {}B val, n={n_per}/thread",
        VAL.len()
    );
    for &t in &[1usize, 2, 4, 8, 10] {
        run("GET", &store, t, n_per, &keys, false);
    }
    for &t in &[1usize, 2, 4, 8, 10] {
        run("SET", &store, t, n_per, &keys, true);
    }
}

pub fn with_metric_sink( self, sink: impl Fn(KevyMetric) + Send + Sync + 'static, ) -> Self

Register a push-style metric callback. It receives a crate::KevyMetric for each AOF replay (startup) and AOF rewrite (compaction) — wire it to Prometheus / a log line / a counter. The callback runs synchronously on the emitting thread (reaper thread for background rewrites), so keep it fast and non-blocking. Replaces any previously-set sink.

pub fn with_ttl_reaper_manual(self) -> Self

Caller-driven TTL reaping — disables the background thread. Required for WASM (no threads available). Call crate::Store::tick yourself from your event loop.

Examples found in repository

examples/bench_embed_mt.rs (line 64)

fn main() {
    let n_per: usize = std::env::var("KEVY_BENCH_N")
        .ok()
        .and_then(|s| s.parse().ok())
        .unwrap_or(2_000_000);
    let keys: Vec<Vec<u8>> = (0..KEYS).map(|i| format!("k{i}").into_bytes()).collect();
    let shards: usize = std::env::var("KEVY_SHARDS")
        .ok()
        .and_then(|s| s.parse().ok())
        .unwrap_or(1);

    // Shared in-memory store (no AOF) — isolate the lock/keyspace from disk.
    let store = Store::open(Config::default().with_shards(shards).with_ttl_reaper_manual()).unwrap();
    for k in &keys {
        store.set(k, VAL).unwrap();
    }

    println!(
        "kevy-embedded MULTI-THREAD throughput — in-memory, shards={shards}, {KEYS} keys, {}B val, n={n_per}/thread",
        VAL.len()
    );
    for &t in &[1usize, 2, 4, 8, 10] {
        run("GET", &store, t, n_per, &keys, false);
    }
    for &t in &[1usize, 2, 4, 8, 10] {
        run("SET", &store, t, n_per, &keys, true);
    }
}

examples/bench_embed.rs (line 56)

fn main() {
    let n: usize = std::env::var("KEVY_BENCH_N")
        .ok()
        .and_then(|s| s.parse().ok())
        .unwrap_or(2_000_000);
    // Keys precomputed outside the timed loop so `format!`/alloc cost isn't
    // attributed to kevy.
    let keys: Vec<Vec<u8>> = (0..KEYS).map(|i| format!("k{i}").into_bytes()).collect();

    println!("kevy-embedded in-process throughput — single thread, n={n}, {KEYS} keys, {}B val", VAL.len());

    let s1 = Store::open(Config::default().with_ttl_reaper_manual()).unwrap();
    bench("in-memory", &s1, n, &keys);

    let dir2 = std::env::temp_dir().join("kevy_embed_bench_everysec");
    let _ = std::fs::remove_dir_all(&dir2);
    let s2 = Store::open(
        Config::default()
            .with_persist(&dir2)
            .with_ttl_reaper_manual()
            .with_appendfsync(AppendFsync::EverySec),
    )
    .unwrap();
    bench("aof-everysec", &s2, n, &keys);

    let dir3 = std::env::temp_dir().join("kevy_embed_bench_always");
    let _ = std::fs::remove_dir_all(&dir3);
    let s3 = Store::open(
        Config::default()
            .with_persist(&dir3)
            .with_ttl_reaper_manual()
            .with_appendfsync(AppendFsync::Always),
    )
    .unwrap();
    // Always-fsync is one fdatasync per write (no group commit on the embedded
    // single-op path) — fsync-rate-bound, so run far fewer ops to stay bounded.
    bench("aof-always", &s3, (n / 20).max(50_000), &keys);

    // TTL'd-key GET: the mailrs path (every cache key has a TTL). With the
    // background reaper the cached clock is trusted (no per-get Instant::now);
    // manual mode reads a fresh clock per get — the gap is the cached-clock win.
    bench_ttl_get("ttl GET (cached clk)", false, n, &keys); // background reaper
    bench_ttl_get("ttl GET (fresh clk) ", true, n, &keys); // manual reaper

    drop((s1, s2, s3));
    let _ = std::fs::remove_dir_all(&dir2);
    let _ = std::fs::remove_dir_all(&dir3);
}

/// GET throughput over keys that all carry a (long) TTL — the mailrs cache
/// shape. `manual_reaper` toggles whether the store trusts the cached clock
/// (background) or reads a fresh clock per get (manual).
fn bench_ttl_get(label: &str, manual_reaper: bool, n: usize, keys: &[Vec<u8>]) {
    let cfg = if manual_reaper {
        Config::default().with_ttl_reaper_manual()
    } else {
        Config::default() // background reaper (default) → cached clock trusted
    };
    let store = Store::open(cfg).unwrap();
    let ttl = std::time::Duration::from_secs(3600); // never expires during the run
    for k in keys {
        store.set_with_ttl(k, VAL, ttl).unwrap();
    }
    let t = Instant::now();
    let mut hits = 0usize;
    for i in 0..n {
        if store.get(&keys[i % KEYS]).unwrap().is_some() {
            hits += 1;
        }
    }
    std::hint::black_box(hits);
    println!("[{label}] GET {:>10.0} ops/s", n as f64 / t.elapsed().as_secs_f64());
}

pub fn with_reaper_interval(self, iv: Duration) -> Self

Override the background reaper interval. Default 100 ms.

pub fn with_snapshot_filename(self, name: impl Into<String>) -> Self

Override the snapshot file name inside data_dir.

pub fn with_aof_filename(self, name: impl Into<String>) -> Self

Override the AOF file name inside data_dir.

Examples found in repository

examples/replay_real_aof.rs (line 36)

fn main() {
    let path = std::env::args()
        .nth(1)
        .expect("usage: replay_real_aof <aof-path>");
    let src = PathBuf::from(&path);
    let bytes = std::fs::metadata(&src)
        .map(|m| m.len())
        .unwrap_or(0);
    println!("reproducer: staging {} bytes from {}", bytes, src.display());

    let dir = std::env::temp_dir().join(format!(
        "kevy-aof-reproducer-{}",
        std::process::id()
    ));
    std::fs::create_dir_all(&dir).expect("create temp dir");
    let staged = dir.join("aof-0.aof");
    std::fs::copy(&src, &staged).expect("copy AOF into staging dir");

    println!("reproducer: opening Store from {}", dir.display());
    let store = Store::open(
        Config::default()
            .with_persist(&dir)
            .with_aof_filename("aof-0.aof"),
    )
    .expect("Store::open");

    println!("reproducer: opened OK; dbsize = {}", store.dbsize());
}

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Config

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Config

fn default() -> Self

Returns the “default value” for a type.