Struct heed::Env

pub struct Env(/* private fields */);

An environment handle constructed by using EnvOpenOptions.

Implementations

impl Env

pub fn real_disk_size(&self) -> Result<u64>

The size of the data file on disk.

Example

use heed::EnvOpenOptions;

let dir = tempfile::tempdir()?;
let size_in_bytes = 1024 * 1024;
let env = unsafe { EnvOpenOptions::new().map_size(size_in_bytes).open(dir.path())? };

let actual_size = env.real_disk_size()? as usize;
assert!(actual_size < size_in_bytes);

pub fn flags(&self) -> Result<Option<EnvFlags>>

Return the raw flags the environment was opened with.

Returns None if the environment flags are different from the EnvFlags set.

pub unsafe fn set_flags(&self, flags: EnvFlags, mode: FlagSetMode) -> Result<()>

Enable or disable the environment’s currently active EnvFlags.

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

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

// Env was opened without flags.
assert_eq!(env.get_flags().unwrap(), EnvFlags::empty().bits());

// Enable a flag after opening.
unsafe { env.set_flags(EnvFlags::NO_SYNC, FlagSetMode::Enable).unwrap(); }
assert_eq!(env.get_flags().unwrap(), EnvFlags::NO_SYNC.bits());

// Disable a flag after opening.
unsafe { env.set_flags(EnvFlags::NO_SYNC, FlagSetMode::Disable).unwrap(); }
assert_eq!(env.get_flags().unwrap(), EnvFlags::empty().bits());

Safety

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

LMDB also requires that only 1 thread calls this function at any given moment. Neither heed or LMDB check for this condition, so the caller must ensure it explicitly.

pub fn get_flags(&self) -> Result<u32>

Return the raw flags the environment is currently set with.

pub fn info(&self) -> EnvInfo

Returns some basic informations about this environment.

pub fn non_free_pages_size(&self) -> Result<u64>

Returns the size used by all the databases in the environment without the free pages.

It is crucial to configure EnvOpenOptions::max_dbs with a sufficiently large value before invoking this function. All databases within the environment will be opened and remain so.

pub fn database_options( &self, ) -> DatabaseOpenOptions<'_, '_, Unspecified, Unspecified>

Options and flags which can be used to configure how a Database is opened.

pub fn open_database<KC, DC>( &self, rtxn: &RoTxn<'_>, name: Option<&str>, ) -> Result<Option<Database<KC, DC>>>

where KC: 'static, DC: 'static,

Opens a typed database that already exists in this environment.

If the database was previously opened in this program run, types will be checked.

Important Information

LMDB has an important restriction on the unnamed database when named ones are opened. The names of the named databases are stored as keys in the unnamed one and are immutable, and these keys can only be read and not written.

LMDB read-only access of existing database

In the case of accessing a database in a read-only manner from another process where you wrote, you might need to manually call RoTxn::commit to get metadata and the database handles opened and shared with the global Env handle.

If not done, you might raise Io(Os { code: 22, kind: InvalidInput, message: "Invalid argument" }) known as EINVAL.

pub fn create_database<KC, DC>( &self, wtxn: &mut RwTxn<'_>, name: Option<&str>, ) -> Result<Database<KC, DC>>

where KC: 'static, DC: 'static,

Creates a typed database that can already exist in this environment.

If the database was previously opened during this program run, types will be checked.

Important Information

LMDB has an important restriction on the unnamed database when named ones are opened. The names of the named databases are stored as keys in the unnamed one and are immutable, and these keys can only be read and not written.

pub fn write_txn(&self) -> Result<RwTxn<'_>>

Create a transaction with read and write access for use with the environment.

LMDB Limitations

Only one RwTxn may exist simultaneously in the current environment. If another write transaction is initiated, while another write transaction exists the thread initiating the new one will wait on a mutex upon completion of the previous transaction.

pub fn nested_write_txn<'p>( &'p self, parent: &'p mut RwTxn<'_>, ) -> Result<RwTxn<'p>>

Create a nested transaction with read and write access for use with the environment.

The new transaction will be a nested transaction, with the transaction indicated by parent as its parent. Transactions may be nested to any level.

A parent transaction and its cursors may not issue any other operations than commit and abort while it has active child transactions.

pub fn read_txn(&self) -> Result<RoTxn<'_>>

Create a transaction with read-only access for use with the environment.

You can make this transaction Sendable between threads by using the read-txn-no-tls crate feature. See Self::static_read_txn if you want the txn to own the environment.

LMDB Limitations

It’s possible to have multiple read transactions in the same environment while there is a write transaction ongoing.

But read transactions prevent reuse of pages freed by newer write transactions, thus the database can grow quickly. Write transactions prevent other write transactions, since writes are serialized.

So avoid long-lived read transactions.

Errors

• crate::MdbError::Panic: A fatal error occurred earlier, and the environment must be shut down
• crate::MdbError::MapResized: Another process wrote data beyond this Env mapsize and this env map must be resized
• crate::MdbError::ReadersFull: a read-only transaction was requested, and the reader lock table is full

pub fn static_read_txn(self) -> Result<RoTxn<'static>>

Create a transaction with read-only access for use with the environment. Contrary to Self::read_txn, this version owns the environment, which means you won’t be able to close the environment while this transaction is alive.

You can make this transaction Sendable between threads by using the read-txn-no-tls crate feature.

LMDB Limitations

It’s possible to have multiple read transactions in the same environment while there is a write transaction ongoing.

But read transactions prevent reuse of pages freed by newer write transactions, thus the database can grow quickly. Write transactions prevent other write transactions, since writes are serialized.

So avoid long-lived read transactions.

Errors

• crate::MdbError::Panic: A fatal error occurred earlier, and the environment must be shut down
• crate::MdbError::MapResized: Another process wrote data beyond this Env mapsize and this env map must be resized
• crate::MdbError::ReadersFull: a read-only transaction was requested, and the reader lock table is full

pub fn copy_to_file<P: AsRef<Path>>( &self, path: P, option: CompactionOption, ) -> Result<File>

Copy an LMDB environment to the specified path, with options.

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

pub unsafe fn copy_to_fd( &self, fd: mdb_filehandle_t, option: CompactionOption, ) -> Result<()>

Copy an LMDB environment to the specified file descriptor, with compaction option.

This function may be used to make a backup of an existing environment. No lockfile is created, since it gets recreated at need.

Safety

The ffi::mdb_filehandle_t must have already been opened for Write access.

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

Flush the data buffers to disk.

pub fn path(&self) -> &Path

Returns the canonicalized path where this env lives.

pub fn prepare_for_closing(self) -> EnvClosingEvent

Returns an EnvClosingEvent that can be used to wait for the closing event, multiple threads can wait on this event.

Make sure that you drop all the copies of Envs you have, env closing are triggered when all references are dropped, the last one will eventually close the environment.

pub fn clear_stale_readers(&self) -> Result<usize>

Check for stale entries in the reader lock table and clear them.

Returns the number of stale readers cleared.

pub unsafe fn resize(&self, new_size: usize) -> Result<()>

Resize the memory map to a new size.

Safety

According to the LMDB documentation, it is okay to call mdb_env_set_mapsize for an open environment as long as no transactions are active, but the library does not check for this condition, so the caller must ensure it explicitly.

pub fn max_key_size(&self) -> usize

Get the maximum size of keys and MDB_DUPSORT data we can write.

Depends on the compile-time constant MDB_MAXKEYSIZE. Default 511

Trait Implementations

impl Clone for Env

fn clone(&self) -> Env

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Env

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

Formats the value using the given formatter.