Mace

Mace is a high-performance, embedded key-value storage engine written in Rust. It is designed to combine the predictable read performance of B+ Trees with the high write throughput of LSM Trees.

Key Features

• Hybrid Performance: Achieves B+ Tree-like read speeds alongside LSM-Tree-like write performance.
• Concurrent MVCC: Supports non-blocking concurrent reads and writes through Multi-Version Concurrency Control.
• Flash-Optimized: Log-structured design specifically tailored for SSD/NVMe endurance and performance.
• Large Value Separation: Efficiently handles large values by separating them from the indexing structure, significantly reducing I/O overhead during maintenance.
• ACID Transactions: Full support for Atomicity, Consistency, Isolation, and Durability.
• Data Integrity: Integrated CRC checksums ensure data remains uncorrupted across restarts and crashes.
• Flow Control: Optional foreground write backpressure to prevent memory pressure spikes.
• Cross-Platform: Native support for Linux, Windows, and macOS.

Installation

cargo add mace-kv

Quick Start

The following example demonstrates basic transaction management and data retrieval:

use mace::{Mace, OpCode, Options};

fn main() -> Result<(), OpCode> {
    // 1. Initialize the storage
    let opts = Options::new("./data_dir");
    let db = Mace::new(opts.validate().unwrap())?;
    let bkt = db.new_bucket("tmp")?;

    // 2. Perform a write transaction
    let txn = bkt.begin()?;
    txn.put("moha", "+1s")?;
    txn.commit()?;

    // 3. Read data using a consistent view
    let view = bkt.view()?;
    let value = view.get("moha")?;
    println!("moha => {:?}", std::str::from_utf8(value.slice()));

    // 4. Remove data
    let txn = bkt.begin()?;
    txn.del("moha")?;
    txn.commit()?;

    Ok(())
}

Detailed usage can be found in examples/demo.rs.

Benchmarks

Mace is engineered for heavy workloads. For detailed performance analysis and comparison with other engines, refer to the kv_bench repository. The summary below is from kv_bench, comparing Mace 0.0.29 with RocksDB 10.4.2.

Benchmark Summary

Workload	Mace wins (ops)	ops median ratio (Mace/RocksDB)	Mace wins (p99)	p99 median ratio (Mace/RocksDB)
W1 (95R/5U, uniform)	16 / 16	2.3x	5 / 16	1.0x
W2 (95R/5U, zipf)	16 / 16	1.5x	11 / 16	0.5x
W3 (50R/50U)	15 / 16	1.4x	9 / 16	0.5x
W4 (5R/95U)	12 / 16	1.3x	7 / 16	1.0x
W5 (70R/25U/5S)	15 / 16	2.1x	16 / 16	0.2x
W6 (100% scan)	16 / 16	4.6x	15 / 16	0.2x

Note: for ops median ratio (Mace/RocksDB), larger means higher Mace throughput. For p99 median ratio (Mace/RocksDB), smaller means lower Mace tail latency.

Recent complete benchmark results: https://o2c.fun/benchmark.html

Test Environment

• OS: openSUSE Tumbleweed
• CPU: AMD Ryzen 5 3600 (6 cores / 12 threads)
• Memory: 32 GiB RAM
• Kernel: Linux 6.19.12-1-default
• Filesystem: xfs (/dev/nvme1n1p4, mounted at /nvme)
• SSD: ZHITAI TiPlus5000 1TB

Validation

• Correctness/crash matrix: ./scripts/prod_test.sh all 8
• Perf regression gate: ./scripts/perf_gate.sh compare
• Script details: scripts/README.md

Design Notes

Architecture and crash-safety notes are in docs/design.md.

Status

mace is not stable yet. Storage format and APIs can change between minor versions.

Discussion

If you want to join the discussion, you are welcome to join the QQ group: 1023032506.

License

This project is licensed under the MIT License - see the LICENSE file for details.