Struct lmdb::Environment

pub struct Environment { /* fields omitted */ }

An LMDB environment.

An environment supports multiple databases, all residing in the same shared-memory map.

Methods

impl Environment

pub fn new() -> EnvironmentBuilder

Creates a new builder for specifying options for opening an LMDB environment.

pub fn env(&self) -> *mut MDB_env

Returns a raw pointer to the underlying LMDB environment.

The caller must ensure that the pointer is not dereferenced after the lifetime of the environment.

pub fn open_db<'env>(&'env self, name: Option<&str>) -> Result<Database>

Opens a handle to an LMDB database.

If name is None, then the returned handle will be for the default database.

If name is not None, then the returned handle will be for a named database. In this case the environment must be configured to allow named databases through EnvironmentBuilder::set_max_dbs.

The returned database handle may be shared among any transaction in the environment.

This function will fail with Error::BadRslot if called by a thread which has an ongoing transaction.

The database name may not contain the null character.

pub fn create_db<'env>(
    &'env self,
    name: Option<&str>,
    flags: DatabaseFlags
) -> Result<Database>

Opens a handle to an LMDB database, creating the database if necessary.

If the database is already created, the given option flags will be added to it.

If name is None, then the returned handle will be for the default database.

If name is not None, then the returned handle will be for a named database. In this case the environment must be configured to allow named databases through EnvironmentBuilder::set_max_dbs.

The returned database handle may be shared among any transaction in the environment.

This function will fail with Error::BadRslot if called by a thread with an open transaction.

pub fn get_db_flags<'env>(&'env self, db: Database) -> Result<DatabaseFlags>

Retrieves the set of flags which the database is opened with.

The database must belong to to this environment.

pub fn begin_ro_txn<'env>(&'env self) -> Result<RoTransaction<'env>>

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

pub fn begin_rw_txn<'env>(&'env self) -> Result<RwTransaction<'env>>

Create a read-write transaction for use with the environment. This method will block while there are any other read-write transactions open on the environment.

pub fn sync(&self, force: bool) -> Result<()>

Flush data buffers to disk.

Data is always written to disk when Transaction::commit is called, but the operating system may keep it buffered. LMDB always flushes the OS buffers upon commit as well, unless the environment was opened with MDB_NOSYNC or in part MDB_NOMETASYNC.

pub unsafe fn close_db(&mut self, db: Database)

Closes the database handle. Normally unnecessary.

Closing a database handle is not necessary, but lets Transaction::open_database reuse the handle value. Usually it's better to set a bigger EnvironmentBuilder::set_max_dbs, unless that value would be large.

Safety

This call is not mutex protected. Databases should only be closed by a single thread, and only if no other threads are going to reference the database handle or one of its cursors any further. Do not close a handle if an existing transaction has modified its database. Doing so can cause misbehavior from database corruption to errors like Error::BadValSize (since the DB name is gone).

pub fn stat(&self) -> Result<Stat>

Retrieves statistics about this environment.

pub fn info(&self) -> Result<Info>

Retrieves info about this environment.

pub fn freelist(&self) -> Result<size_t>

Retrieves the total number of pages on the freelist.

Along with Environment::info(), this can be used to calculate the exact number of used pages as well as free pages in this environment.

let env = Environment::new().open("/tmp/test").unwrap();
let info = env.info().unwrap();
let stat = env.stat().unwrap();
let freelist = env.freelist().unwrap();
let last_pgno = info.last_pgno() + 1; // pgno is 0 based.
let total_pgs = info.map_size() / stat.page_size() as usize;
let pgs_in_use = last_pgno - freelist;
let pgs_free = total_pgs - pgs_in_use;

Note:

• LMDB stores all the freelists in the designated database 0 in each environment, and the freelist count is stored at the beginning of the value as libc::size_t in the native byte order.

• It will create a read transaction to traverse the freelist database.

pub fn set_map_size(&self, size: size_t) -> Result<()>

Sets the size of the memory map to use for the environment.

This could be used to resize the map when the environment is already open.

Note:

• No active transactions allowed when performing resizing in this process.

• The size should be a multiple of the OS page size. Any attempt to set a size smaller than the space already consumed by the environment will be silently changed to the current size of the used space.

• In the multi-process case, once a process resizes the map, other processes need to either re-open the environment, or call set_map_size with size 0 to update the environment. Otherwise, new transaction creation will fail with Error::MapResized.

Trait Implementations

impl Drop for Environment

fn drop(&mut self)

Executes the destructor for this type.

impl Sync for Environment

impl Send for Environment

impl Debug for Environment

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

Formats the value using the given formatter.