Struct EnvOpenOptions

Source

pub struct EnvOpenOptions { /* private fields */ }

Expand description

Options and flags which can be used to configure how an environment is opened.

Implementations§

Source §

impl EnvOpenOptions

Source

pub fn new() -> EnvOpenOptions

Creates a blank new set of options ready for configuration.

Source

pub fn write_admission(&mut self, admission: WriteAdmission) -> &mut Self

Install admission before environment initialization and every physical data write or lock-file extension. Clone one handle for compatible opens.

Source

pub fn map_size(&mut self, size: usize) -> &mut Self

Set the size of the memory map to use for this environment.

Source

pub fn max_readers(&mut self, readers: u32) -> &mut Self

Set the maximum number of threads/reader slots for the environment.

Source

pub fn max_dbs(&mut self, dbs: u32) -> &mut Self

Set the maximum number of named databases for the environment.

Source

pub unsafe fn flags(&mut self, flags: EnvFlags) -> &mut Self

Set one or more LMDB flags.

use std::fs;
use std::path::Path;
use heed::{EnvOpenOptions, Database, EnvFlags};
use heed::types::*;

fs::create_dir_all(Path::new("target").join("database.mdb"))?;
let mut env_builder = EnvOpenOptions::new();
unsafe { env_builder.flags(EnvFlags::NO_TLS | EnvFlags::NO_META_SYNC); }
let dir = tempfile::tempdir().unwrap();
let env = unsafe { env_builder.open(dir.path())? };

// we will open the default unnamed database
let mut wtxn = env.write_txn()?;
let db: Database<Str, U32<byteorder::NativeEndian>> = env.create_database(&mut wtxn, None)?;

// opening a write transaction
db.put(&mut wtxn, "seven", &7)?;
db.put(&mut wtxn, "zero", &0)?;
db.put(&mut wtxn, "five", &5)?;
db.put(&mut wtxn, "three", &3)?;
wtxn.commit()?;

// force the OS to flush the buffers (see Flag::NoSync and Flag::NoMetaSync).
env.force_sync();

// opening a read transaction
// to check if those values are now available
let mut rtxn = env.read_txn()?;

let ret = db.get(&rtxn, "zero")?;
assert_eq!(ret, Some(0));

let ret = db.get(&rtxn, "five")?;
assert_eq!(ret, Some(5));

§Safety

It is unsafe to use unsafe LMDB flags such as NO_SYNC, NO_META_SYNC, or NO_LOCK.

Source

pub unsafe fn open<P: AsRef<Path>>(&self, path: P) -> Result<Env>

Open an environment that will be located at the specified path.

§Safety

LMDB is backed by a memory map ¹ which comes with some safety precautions.

Memory map constructors are marked unsafe because of the potential for Undefined Behavior (UB) using the map if the underlying file is subsequently modified, in or out of process.

LMDB itself has a locking system that solves this problem, but it will not save you from making mistakes yourself.

These are some things to take note of:

Avoid long-lived transactions, they will cause the database to grow quickly ²
Avoid aborting your process with an active transaction ³
Do not use LMDB on remote filesystems, even between processes on the same host ⁴
You must manage concurrent accesses yourself if using EnvFlags::NO_LOCK ⁵
Anything that causes LMDB’s lock file to be broken will cause synchronization issues and may introduce UB ⁶

heed itself upholds some safety invariants, including but not limited to:

Calling EnvOpenOptions::open twice in the same process, at the same time is OK ⁷

For more details, it is highly recommended to read LMDB’s official documentation. ⁸

Source

pub unsafe fn open_from_pinned_path<P: AsRef<Path>>( &self, path: P, pinned: PinnedLmdbIdentity, ) -> Result<Env>

Opens an environment through an already-pinned absolute path without canonicalizing it first.

This is intended for Linux /proc/self/fd/N directory handles. The ordinary Self::open canonicalization would turn such a handle back into a mutable pathname before LMDB opens its files, defeating the caller’s retained directory descriptor.

§Safety

In addition to Self::open’s requirements, path must be an absolute, process-owned, retained path whose identity cannot be redirected for the lifetime of the returned environment.