Struct Options 

pub struct Options {

    pub sync_on_write: bool,
    pub concurrent_write: u8,
    pub gc_timeout: u64,
    pub checkpoint_nudge_ms: u64,
    pub data_garbage_ratio: u32,
    pub gc_eager: bool,
    pub blob_file_size: usize,
    pub blob_garbage_ratio: usize,
    pub blob_gc_ratio: usize,
    pub tmp_store: bool,
    pub log_root: PathBuf,
    pub lru_capacity: usize,
    pub stat_mask_cache_count: usize,
    pub data_handle_cache_capacity: usize,
    pub blob_handle_cache_capacity: usize,
    pub data_file_size: usize,
    pub wal_buffer_size: usize,
    pub max_ckpt_per_txn: usize,
    pub wal_file_size: u32,
    pub keep_stable_wal_file: bool,
    pub truncate_corrupted_wal: bool,
    pub observer: Arc<dyn Observer>,
    /* private fields */
}

Configuration options for the Mace storage engine.

Fields

sync_on_write: bool

Force-sync data to disk for every wal/data write.

The default value is true (use fsync or else use fdatasync). Turning it off may result in data loss, while turning it on may reduce performance.

concurrent_write: u8

Writer group count. Default is Self::CONCURRENT_WRITE and it must be in the range [1, 128]

Once set, it cannot be modified

gc_timeout: u64

Garbage collection cycle interval (milliseconds).

checkpoint_nudge_ms: u64

Proactive page-checkpoint trigger interval (milliseconds).

When a bucket has pending dirty pages but no foreground write reaches checkpoint thresholds, the evictor triggers checkpoint near this interval to prevent WAL checkpoint stalling.

Set to 0 to disable proactive triggering.

data_garbage_ratio: u32

Perform compaction when the garbage ratio exceeds this value, in the range [0, 100]

gc_eager: bool

If true, compact immediately when Self::data_garbage_ratio is reached.

blob_file_size: usize

Size limit of a blob file. Default is Self::BLOB_FILE_SIZE

blob_garbage_ratio: usize

Trigger blob GC when the garbage ratio exceeds this value, in the range [0, 100]

blob_gc_ratio: usize

At each blob GC cycle, pick the lowest-utilization Self::blob_gc_ratio% of blob files as candidates.

tmp_store: bool

Whether this is temporary storage.

If true, db_root will be removed on exit.

log_root: PathBuf

Directory where log files are stored.

The default value is db_root/log.

lru_capacity: usize

Shared logical-address cache capacity in bytes.

This cache keeps file-loaded blob values and auxiliary history/sibling pages. Resident tree pages and dirty pool pages are accounted elsewhere and are not inserted here. Trimming is best-effort and happens in small rounds, so short-term overshoot is possible.

Different subsystems may transiently hold refs to the same allocation.

stat_mask_cache_count: usize

Bitmap-cache entry count for data and blob stats.

data_handle_cache_capacity: usize

Maximum number of open data-file handles cached concurrently, used for loading data pages.

blob_handle_cache_capacity: usize

Maximum number of open blob-file handles cached concurrently, used for loading blob pages.

data_file_size: usize

Size limit of a data file. Minimum is Self::DATA_FILE_SIZE

wal_buffer_size: usize

WAL ring buffer size. Must be greater than the page size and a power of two.

max_ckpt_per_txn: usize

Number of checkpoints a transaction can span (i.e., transaction length limit).

If a transaction exceeds this limit, it is forcibly aborted.

wal_file_size: u32

WAL file size limit that triggers switching to a new WAL file, up to 2GB.

keep_stable_wal_file: bool

If true, remove unused stable WAL files (never used in recovery).

Default is false.

truncate_corrupted_wal: bool

If true, corrupted WAL is truncated during recovery; otherwise recovery panics.

Default is true.

observer: Arc<dyn Observer>

Observability callback. Default is no-op.

Implementations

impl Options

pub const CONCURRENT_WRITE: u8 = 16

pub const MAX_CONCURRENT_WRITE: u8 = 128

pub const DATA_FILE_SIZE: usize

pub const BLOB_FILE_SIZE: usize

pub const LRU_CAPACITY: usize

pub const STAT_MASK_CACHE_CNT: usize = 16384

pub const WAL_BUF_SZ: usize

pub const WAL_FILE_SZ: usize

pub fn new<P: AsRef<Path>>(db_root: P) -> Self

Creates a new Options instance with default values and the given database root.

Examples found in repository

examples/observer.rs (line 13)

fn main() -> Result<(), OpCode> {
    let path = std::env::temp_dir().join(format!("mace_observer_{}", std::process::id()));
    let _ = std::fs::remove_dir_all(&path);

    let observer = Arc::new(InMemoryObserver::new(256));
    let mut opt = Options::new(&path);
    opt.observer = observer.clone();

    let db = Mace::new(opt.validate()?)?;
    let bucket = db.new_bucket("observe", BucketOptions::default())?;

    let tx = bucket.begin()?;
    tx.put("k1", "v1")?;

    let r = tx.put("k1", "v2");
    assert_eq!(r.err(), Some(OpCode::AbortTx));
    drop(tx);

    let tx = bucket.begin()?;
    tx.put("k2", "v2")?;
    tx.commit()?;

    let snapshot = observer.snapshot();
    print_snapshot(&snapshot);
    Ok(())
}

examples/demo.rs (line 6)

fn main() -> Result<(), OpCode> {
    let path = std::env::temp_dir().join("mace");
    let _ = std::fs::remove_dir_all(&path);
    let opt = Options::new(path).validate()?;
    let db = Mace::new(opt)?;
    let bucket = db.new_bucket("test", BucketOptions::default())?;

    // start a read-write transaction
    let kv = bucket.begin()?;
    kv.put("foo", "bar")?;
    kv.put("fool", "+1s")?;
    kv.put("foolish", "elder")?;

    // can't create two identical keys
    let r = kv.put("foolish", "114514").err();
    assert_eq!(r.unwrap(), OpCode::AbortTx);

    // use `update` for exist key or use `upsert` when unsure
    let r = kv.update("foolish", "114514");
    assert!(r.is_ok());

    let r = kv.get("foo")?;
    assert_eq!(r.slice(), "bar".as_bytes());
    kv.del("foolish")?;
    kv.commit()?;

    // rollback
    let kv = bucket.begin()?;
    kv.put("mo", "ha")?;
    drop(kv);

    // start a read-only transaction
    let view = bucket.view()?;
    let r = view.get("foo")?;
    assert_eq!(r.slice(), "bar".as_bytes());
    let r = view.get("mo");
    assert_eq!(r.err().unwrap(), OpCode::NotFound);

    // prefix scan
    let r = view.get("foolish");
    assert!(r.is_err() && r.err().unwrap() == OpCode::NotFound);
    let iter = view.seek("foo");
    assert_eq!(iter.count(), 2);

    Ok(())
}

pub fn validate(self) -> Result<ParsedOptions, OpCode>

Validates the options and returns a ParsedOptions instance.

Examples found in repository

examples/observer.rs (line 16)

fn main() -> Result<(), OpCode> {
    let path = std::env::temp_dir().join(format!("mace_observer_{}", std::process::id()));
    let _ = std::fs::remove_dir_all(&path);

    let observer = Arc::new(InMemoryObserver::new(256));
    let mut opt = Options::new(&path);
    opt.observer = observer.clone();

    let db = Mace::new(opt.validate()?)?;
    let bucket = db.new_bucket("observe", BucketOptions::default())?;

    let tx = bucket.begin()?;
    tx.put("k1", "v1")?;

    let r = tx.put("k1", "v2");
    assert_eq!(r.err(), Some(OpCode::AbortTx));
    drop(tx);

    let tx = bucket.begin()?;
    tx.put("k2", "v2")?;
    tx.commit()?;

    let snapshot = observer.snapshot();
    print_snapshot(&snapshot);
    Ok(())
}

examples/demo.rs (line 6)

fn main() -> Result<(), OpCode> {
    let path = std::env::temp_dir().join("mace");
    let _ = std::fs::remove_dir_all(&path);
    let opt = Options::new(path).validate()?;
    let db = Mace::new(opt)?;
    let bucket = db.new_bucket("test", BucketOptions::default())?;

    // start a read-write transaction
    let kv = bucket.begin()?;
    kv.put("foo", "bar")?;
    kv.put("fool", "+1s")?;
    kv.put("foolish", "elder")?;

    // can't create two identical keys
    let r = kv.put("foolish", "114514").err();
    assert_eq!(r.unwrap(), OpCode::AbortTx);

    // use `update` for exist key or use `upsert` when unsure
    let r = kv.update("foolish", "114514");
    assert!(r.is_ok());

    let r = kv.get("foo")?;
    assert_eq!(r.slice(), "bar".as_bytes());
    kv.del("foolish")?;
    kv.commit()?;

    // rollback
    let kv = bucket.begin()?;
    kv.put("mo", "ha")?;
    drop(kv);

    // start a read-only transaction
    let view = bucket.view()?;
    let r = view.get("foo")?;
    assert_eq!(r.slice(), "bar".as_bytes());
    let r = view.get("mo");
    assert_eq!(r.err().unwrap(), OpCode::NotFound);

    // prefix scan
    let r = view.get("foolish");
    assert!(r.is_err() && r.err().unwrap() == OpCode::NotFound);
    let iter = view.seek("foo");
    assert_eq!(iter.count(), 2);

    Ok(())
}

pub fn create_dir(&self) -> Result<()>

Creates the directory structure for the database.

impl Options

pub const SEP: &'static str = "_"

pub const DATA_PREFIX: &'static str = "data"

pub const BLOB_PREFIX: &'static str = "blob"

pub const WAL_PREFIX: &'static str = "wal"

pub const WAL_STABLE: &'static str = "stable-wal"

pub const MANIFEST: &'static str = "manifest"

pub fn data_root(&self) -> PathBuf

pub fn data_file(&self, id: u64) -> PathBuf

pub fn blob_file(&self, id: u64) -> PathBuf

pub fn log_root(&self) -> PathBuf

pub fn db_root(&self) -> PathBuf

pub fn wal_file(&self, group_id: u8, seq: u64) -> PathBuf

pub fn wal_backup(&self, group_id: u8, seq: u64) -> PathBuf

pub fn manifest(&self) -> PathBuf

Trait Implementations

impl Clone for Options

fn clone(&self) -> Options

Returns a duplicate of the value.

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

Performs copy-assignment from source.