Struct Environment

Source
pub struct Environment { /* private fields */ }
Expand description

An LMDB environment which has been opened to a file.

Implementations§

Source§

impl Environment

Source

pub unsafe fn from_raw(env: *mut MDB_env) -> Self

Wrap a raw LMDB environment handle in an Environment.

The Environment assumes ownership of the MDB_env. If you do not want this, see borrow_raw() instead.

§Unsafety

env must point to a valid MDB_env.

It is the caller’s responsibility to ensure that nothing destroys the MDB_env before into_raw() is called, and that nothing attempts to use the MDB_env after Environment is dropped normally.

It is safe for multiple Environments bound to the same MDB_env to coexist (though the others would need to be created by borrow_raw). However, care must be taken when using databases since by default the Environment will assume ownership of those as well.

Source

pub unsafe fn borrow_raw(env: *mut MDB_env) -> Self

Wrap a raw LMDB environment handle in an Environment without taking ownership.

The Environment does not assume ownership of the MDB_env, and will not destroy it when it is dropped. See from_raw() if taking ownership is desired.

Note that this does not affect assumed ownership of MDB_dbi handles; databases opened by Database::open are still presumed owned.

§Unsafety

env must point to a valid MDB_env.

It is safe for multiple Environments bound to the same MDB_env to coexist (though the others would need to be created by borrow_raw). However, care must be taken when using databases since by default the Environment will assume ownership of those as well.

Source

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

Return the underlying MDB_env handle.

§Safety

While this call is in and of itself safe, the caller must ensure that operations against the backing store do not violate Rust aliasing rules, and must not take any action that would cause the MDB_env to be destroyed prematurely, or to use it after this Environment is destroyed.

Source

pub fn into_raw(self) -> *mut MDB_env

Consume this Environment and return the underlying handle.

After this call, it is the caller’s responsibility to ensure that the MDB_env is eventually destroyed, if it was actually owned by this Environment (compare from_raw and borrow_raw).

§Safety

While this call is in and of itself safe, the caller must ensure that operations against the backing store do not violate Rust aliasing rules.

Source

pub fn copy(&self, path: &str, flags: Flags) -> Result<()>

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.

§Note

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Caveats.

§Example
let out = tempdir::TempDir::new_in(".", "lmdbcopy").unwrap();
env.copy(out.path().to_str().unwrap(),
         lmdb::copy::COMPACT).unwrap();
// We could now open up an independent environment in `lmdbcopyXXXX`
// or upload it somewhere, eg, while `env` could continue being
// modified concurrently.
Source

pub fn copyfd(&self, fd: Fd, flags: Flags) -> Result<()>

Copy an LMDB environment to the specified file descriptor, 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. See copy() for further details.

§Note

This call can trigger significant file size growth if run in parallel with write transactions, because it employs a read-only transaction. See long-lived transactions under Caveats.

Source

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

Return statistics about the LMDB environment.

Source

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

Return information about the LMDB environment.

Source

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

Flush the data buffers to disk.

Data is always written to disk when transactions are committed, but the operating system may keep it buffered. LMDB always flushes the OS buffers upon commit as well, unless the environment was opened with NOSYNC or in part NOMETASYNC. This call is not valid if the environment was opened with RDONLY.

If force is true, force a synchronous flush. Otherwise if the environment has the NOSYNC flag set the flushes will be omitted, and with MAPASYNC they will be asynchronous.

Source

pub unsafe fn set_flags(&self, flags: Flags, onoff: bool) -> Result<()>

Set environment flags.

This may be used to set some flags in addition to those from EnvBuilder::open(), or to unset these flags. If several threads change the flags at the same time, the result is undefined.

flags specifies the flags to edit, not the new status of all flags. If onoff is true, all flags in flags are set; otherwise, all flags in flags are cleared.

§Unsafety

The caller must ensure that multiple threads do not call this concurrently with itself or with get_flags(). This could not be accomplished by using &mut self, since any open databases necessarily have the environment borrowed already.

§Example
unsafe {
  // Enable the NOMETASYNC and MAPASYNC flags
  env.set_flags(lmdb::open::NOMETASYNC | lmdb::open::MAPASYNC, true)
    .unwrap();
  assert!(env.flags().unwrap().contains(
    lmdb::open::NOMETASYNC | lmdb::open::MAPASYNC));
  // Turn MAPASYNC back off, leaving NOMETASYNC set
  env.set_flags(lmdb::open::MAPASYNC, false).unwrap();
  assert!(env.flags().unwrap().contains(lmdb::open::NOMETASYNC));
  assert!(!env.flags().unwrap().contains(lmdb::open::MAPASYNC));
}
Source

pub fn flags(&self) -> Result<Flags>

Get environment flags.

Source

pub fn path(&self) -> Result<&CStr>

Return the path that was used in EnvBuilder::open().

§Panics

Panics if LMDB returns success but sets the path to a NULL pointer.

Source

pub unsafe fn fd(&self) -> Result<Fd>

Return the filedescriptor for the given environment.

§Unsafety

The caller must ensure that the file descriptor is not used to subvert normal LMDB functionality, such as by writing to it or closing it.

Source

pub unsafe fn set_mapsize(&self, size: usize) -> Result<()>

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

The size should be a multiple of the OS page size. The default is 10485760 bytes. The size of the memory map is also the maximum size of the database. The value should be chosen as large as possible, to accommodate future growth of the database.

The new size takes effect immediately for the current process but will not be persisted to any others until a write transaction has been committed by the current process. Also, only mapsize increases are persisted into the environment.

If the mapsize is increased by another process, and data has grown beyond the range of the current mapsize, starting a transaction will return error::MAP_RESIZED. This function may be called with a size of zero to adopt the new size.

§Unsafety

This may only be called if no transactions are active in the current process. Note that the library does not check for this condition, the caller must ensure it explicitly.

Source

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

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

Source

pub fn maxkeysize(&self) -> u32

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

Depends on the compile-time constant MDB_MAXKEYSIZE in LMDB. Default 511.

Source

pub fn reader_check(&self) -> Result<i32>

Check for stale entries in the reader lock table.

Returns the number of stale slots that were cleared.

Trait Implementations§

Source§

impl Debug for Environment

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> SafeBorrow<T> for T
where T: ?Sized,

Source§

fn borrow_replacement(ptr: &T) -> &T

Given ptr, which was obtained from a prior call to Self::borrow(), return a value with the same nominal lifetime which is guaranteed to survive mutations to Self. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.