Skip to main content

Crate oxifaster

Crate oxifaster 

Source
Expand description

§oxifaster - A High-Performance Concurrent Key-Value Store and Log Engine

oxifaster is a Rust port of Microsoft’s FASTER project, providing a high-performance concurrent key-value store and log engine designed for data-intensive applications.

§Overview

This library provides two main components:

  • FasterKV: A concurrent key-value store that supports data larger than memory with seamless disk spillover via a hybrid log architecture.
  • FasterLog: A high-performance persistent recoverable append-only log.

§Key Features

  • High-Performance Concurrent Operations: Lock-free data structures with epoch-based memory reclamation ensure safe and efficient concurrent access.
  • Hybrid Log Architecture: Automatic tiering between in-memory (mutable + read-only) and on-disk storage regions.
  • Non-Blocking Checkpointing: CPR (Concurrent Prefix Recovery) protocol enables checkpoints without stopping operations.
  • Read Cache: Optional in-memory cache for frequently accessed cold data.
  • Log Compaction: Space reclamation through background compaction of obsolete records.
  • Dynamic Index Growth: Hash table can grow dynamically with minimal disruption.
  • F2 Architecture: Two-tier hot-cold data separation for optimized access patterns.
  • Async I/O: Full async/await support with Tokio runtime.

§Quick Start

§Basic Key-Value Operations

ⓘ
use std::sync::Arc;
use oxifaster::device::NullDisk;
use oxifaster::store::{FasterKv, FasterKvConfig};

// Create a store with default configuration
let config = FasterKvConfig::default();
let device = NullDisk::new();
let store = Arc::new(FasterKv::new(config, device));

// Start a session (required for all operations)
let mut session = store.start_session().expect("failed to start session");

// Insert or update a key-value pair
session.upsert(42u64, 100u64);

// Read a value
if let Ok(Some(value)) = session.read(&42u64) {
    println!("Value: {}", value);
}

// Delete a key
session.delete(&42u64);

// Read-Modify-Write operation
session.rmw(42u64, |value| {
    *value += 1;
    true // return true to apply the modification
});

§Checkpoint and Recovery

ⓘ
use std::path::Path;

// Create a checkpoint
let checkpoint_dir = Path::new("/path/to/checkpoints");
let token = store.checkpoint(checkpoint_dir)?;

// Later, recover from the checkpoint
let recovered_store = FasterKv::recover(
    checkpoint_dir,
    token,
    config,
    device
)?;

// Continue sessions from checkpoint
for session_state in recovered_store.get_recovered_sessions() {
    let session = recovered_store
        .continue_session(session_state)
        .expect("failed to continue session");
    // Use the recovered session...
}

§With Read Cache

ⓘ
use oxifaster::cache::ReadCacheConfig;

let cache_config = ReadCacheConfig::new(256 * 1024 * 1024); // 256 MB cache
let store = FasterKv::with_read_cache(config, device, cache_config);

§Log Compaction

ⓘ
// Manual compaction
let result = store.log_compact();
println!("Compacted {} records", result.stats.records_compacted);

// Check if compaction is recommended
if store.should_compact() {
    store.log_compact();
}

§Architecture

┌─────────────────────────────────────────────────────────────┐
│                        Application                          │
├─────────────────────────────────────────────────────────────┤
│                   Session / AsyncSession                    │
├──────────────────────────┬──────────────────────────────────┤
│       FasterKV           │         FasterLog                │
├──────────────────────────┼──────────────────────────────────┤
│       Read Cache         │       Log Compaction             │
├──────────────────────────┴──────────────────────────────────┤
│                     Epoch Protection                        │
├───────────────────────────┬─────────────────────────────────┤
│    Hash Index             │     Hybrid Log                  │
│   (MemHashIndex)          │  ┌────────┬────────┬────────┐   │
│                           │  │Mutable │ReadOnly│On-Disk │   │
│                           │  │Region  │Region  │Region  │   │
│                           │  └────────┴────────┴────────┘   │
├─────────────────────────────────────────────────────────────┤
│                    Storage Device Layer                     │
│         (NullDisk / FileSystemDisk / IoUring)               │
└─────────────────────────────────────────────────────────────┘

§Module Organization

ModuleDescription
address48-bit logical address system for hybrid log
allocatorHybrid log memory allocator (PersistentMemoryMalloc)
cacheRead cache for hot data acceleration
checkpointCheckpoint and recovery with CPR protocol
compactionLog compaction for space reclamation
configConfiguration loading helpers
delta_logDelta log for incremental checkpoints
deviceStorage device abstraction layer
epochEpoch-based memory reclamation framework
[f2]F2 two-tier hot-cold storage architecture
indexHigh-performance in-memory hash index
logFasterLog append-only log
opsOperational helpers for self-check and recovery
recordRecord format and Key/Value traits
scanLog scanning and iteration
statsStatistics collection and reporting
statusOperation status codes
storeFasterKV core implementation
varlenVariable-length record support

§Performance Considerations

  • Session Affinity: Each thread should have its own session for optimal performance. Sessions are not thread-safe and are designed for single-threaded use.
  • Epoch Protection: Operations are protected by epochs. Long-running operations may delay memory reclamation.
  • Page Size: Larger pages reduce metadata overhead but may increase I/O latency.
  • Mutable Fraction: Controls how much of the log is available for in-place updates.

§Feature Flags

  • statistics: Enable comprehensive statistics collection (slight performance overhead)
  • prometheus: Enable Prometheus text exposition rendering for statistics snapshots

Re-exports§

pub use address::Address;
pub use address::AtomicAddress;
pub use record::RecordInfo;
pub use status::OperationStatus;
pub use status::Status;

Modules§

address
Address types for FASTER’s hybrid log
allocator
Memory allocators for FASTER
buffer_pool
Sector-aligned buffer pool for I/O operations
cache
Read cache for FASTER
checkpoint
Checkpoint and recovery for FASTER
codec
Encoding/decoding model for persistence.
compaction
Log compaction for FASTER
config
Configuration loading helpers.
constants
Constants used throughout the library
delta_log
Delta Log for Incremental Checkpoints
device
Storage device abstraction for FASTER
epoch
Epoch-based memory reclamation for FASTER
format
格式识别和版本管理
gc
Garbage collection state management for FASTER
index
Hash index for FASTER
log
FASTER Log implementation
ops
Operational helpers for self-check and recovery.
prelude
Prelude module for common imports
record
Record header for the hybrid log.
scan
Log scanning and iteration for FASTER
size
Utility for size literals (e.g., 1_GiB)
stats
Statistics collection system for FASTER
status
Status codes and operation results for FASTER operations
store
FasterKV key-value store implementation
varlen
Variable Length Records

Structs§

ThreadPoolConfig
Thread pool configuration for background operations