Struct EnvOpenOptions

pub struct EnvOpenOptions { /* private fields */ }

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

Implementations

impl EnvOpenOptions

pub fn new() -> EnvOpenOptions

Creates a blank new set of options ready for configuration.

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

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

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

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

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

Set the maximum number of named databases for the environment.

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.

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. ⁸

---

1. https://en.wikipedia.org/wiki/Memory_map ↩

2. https://github.com/LMDB/lmdb/blob/b8e54b4c31378932b69f1298972de54a565185b1/libraries/liblmdb/lmdb.h#L107-L114 ↩

3. https://github.com/LMDB/lmdb/blob/b8e54b4c31378932b69f1298972de54a565185b1/libraries/liblmdb/lmdb.h#L118-L121 ↩

4. https://github.com/LMDB/lmdb/blob/b8e54b4c31378932b69f1298972de54a565185b1/libraries/liblmdb/lmdb.h#L129 ↩

5. https://github.com/LMDB/lmdb/blob/b8e54b4c31378932b69f1298972de54a565185b1/libraries/liblmdb/lmdb.h#L129 ↩

6. https://github.com/LMDB/lmdb/blob/b8e54b4c31378932b69f1298972de54a565185b1/libraries/liblmdb/lmdb.h#L49-L52 ↩

7. https://github.com/LMDB/lmdb/blob/b8e54b4c31378932b69f1298972de54a565185b1/libraries/liblmdb/lmdb.h#L102-L105 ↩

8. http://www.lmdb.tech/doc/index.html ↩

Trait Implementations

impl Clone for EnvOpenOptions

fn clone(&self) -> EnvOpenOptions

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for EnvOpenOptions

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

Formats the value using the given formatter.

impl Default for EnvOpenOptions

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for EnvOpenOptions

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for EnvOpenOptions

fn eq(&self, other: &EnvOpenOptions) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for EnvOpenOptions

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for EnvOpenOptions

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 40 bytes