Struct lmdb_zero::WriteAccessor

pub struct WriteAccessor<'txn>(_);

A read-write data accessor obtained from a WriteTransaction.

All operations that can be performed on ConstAccessor can also be performed on WriteAccessor.

Lifetime

Nominally, WriteAccessor would behave the same as ConstAccessor.

However, there is never any useful reason to explicitly reference a &WriteAccessor (ie, a shared reference). Instead, one talks about a &mut WriteAccessor. The unfortunate consequence here is that the 'txn lifetime ends up being invariant; that is, the following code will not compile:

fn convariance<'x, 'y>(db: &mut lmdb::WriteAccessor<'x>)
where 'x: 'y {
  let _db2: &mut lmdb::WriteAccessor<'y> = db; // ERROR!
}

The compiler's error messages here tend to be unhelpful. In certain cases, it will suggest changing the function declaration above to something like &'x mut lmdb::WriteAccessor<'x>. Applying such a fix when it is suggested will appear to work. But what happens is that you end up propagating &'txn mut lmdb::WriteAccessor<'txn> the whole way up your call stack. Since 'txn is invariant, it is inferred to be exactly equal to the lifetime of the transaction, and now you've declared that the borrow from the transaction exists for the entire lifetime of the transaction. This means that you cannot actually commit the transaction.

Instead, make sure you always have separate type parameters on the &mut and the WriteAccessor itself. This can usually be accomplished by letting lifetime elision run its course. If you must name both, generally go with &'access mut WriteAccessor<'txn>. The 'access lifetime is the lifetime of any data you obtain via the accessor.

Methods

impl<'txn> WriteAccessor<'txn>

pub fn put<K: AsLmdbBytes + ?Sized, V: AsLmdbBytes + ?Sized>(
    &mut self,
    db: &Database,
    key: &K,
    value: &V,
    flags: Flags
) -> Result<()>

Store items into a database.

This function stores key/data pairs in the database. The default behavior is to enter the new key/data pair, replacing any previously existing key if duplicates are disallowed, or adding a duplicate data item if duplicates are allowed (DUPSORT).

pub fn put_reserve<K: AsLmdbBytes + ?Sized, V: FromReservedLmdbBytes + Sized>(
    &mut self,
    db: &Database,
    key: &K,
    flags: Flags
) -> Result<&mut V>

Store items into a database.

This function stores key/data pairs in the database. The default behavior is to enter the new key/data pair, replacing any previously existing key if duplicates are disallowed, or adding a duplicate data item if duplicates are allowed (DUPSORT).

Unlike put(), this does not take a value. Instead, it reserves space for the value (equal to the size of V) and then returns a mutable reference to it. Be aware that the FromReservedLmdbBytes conversion will be invoked on whatever memory happens to be at the destination location.

Example

#[repr(C, packed)]
#[derive(Clone,Copy,Debug,PartialEq,Eq)]
struct MyStruct {
  x: i32,
  y: i32,
}
unsafe impl lmdb::traits::LmdbRaw for MyStruct { }

let txn = lmdb::WriteTransaction::new(&env).unwrap();
{
  let mut access = txn.access();
  {
    let dst: &mut MyStruct = access.put_reserve(
      &db, "foo", lmdb::put::Flags::empty()).unwrap();
    // Writing to `dst` actually writes directly into the database.
    dst.x = 42;
    dst.y = 56;
    // Drop `dst` so we can use `access` again
  }
  assert_eq!(&MyStruct { x: 42, y: 56 },
             access.get(&db, "foo").unwrap());
}
txn.commit().unwrap();

pub fn put_reserve_array<K: AsLmdbBytes + ?Sized, V: LmdbRaw>(
    &mut self,
    db: &Database,
    key: &K,
    count: usize,
    flags: Flags
) -> Result<&mut [V]>

Store items into a database.

This function stores key/data pairs in the database. The default behavior is to enter the new key/data pair, replacing any previously existing key if duplicates are disallowed, or adding a duplicate data item if duplicates are allowed (DUPSORT).

Unlike put(), this does not take a value. Instead, it reserves space for the value (equal to an array of count objects of size V) and then returns a mutable reference to it. Be aware that the content of the returned slice is simply whatever happens to be in the destination memory at the time of this call.

Example

let txn = lmdb::WriteTransaction::new(&env).unwrap();
{
  let mut access = txn.access();
  {
    let bytes: &mut [u8] = access.put_reserve_array(
      &db, "foo", 4, lmdb::put::Flags::empty()).unwrap();
    // More realistically, one could zero-copy data from a file/socket
    // into `bytes`, for example.
    bytes[0] = b'b'; bytes[1] = b'y';
    bytes[2] = b't'; bytes[3] = b'e';
  }
  assert_eq!("byte", access.get::<str,str>(&db, "foo").unwrap());
}
txn.commit().unwrap();

pub unsafe fn put_reserve_unsized<K: AsLmdbBytes + ?Sized, V: FromReservedLmdbBytes + ?Sized>(
    &mut self,
    db: &Database,
    key: &K,
    size: usize,
    flags: Flags
) -> Result<&mut V>

Store items into a database.

This function stores key/data pairs in the database. The default behavior is to enter the new key/data pair, replacing any previously existing key if duplicates are disallowed, or adding a duplicate data item if duplicates are allowed (DUPSORT).

Unlike put(), this does not take a value. Instead, it reserves space equal to size bytes for the value and then returns a mutable reference to it. Be aware that the FromReservedLmdbBytes conversion will be invoked on whatever memory happens to be at the destination location.

Unsafety

The caller must ensure that size is a valid size for V.

pub fn del_key<K: AsLmdbBytes + ?Sized>(
    &mut self,
    db: &Database,
    key: &K
) -> Result<()>

Delete items from a database by key.

This function removes key/data pairs from the database. All values whose key matches key are deleted, including in the case of DUPSORT. This function will return NOTFOUND if the specified key is not in the database.

Example

let db = lmdb::Database::open(
  &env, Some("example"),
  &lmdb::DatabaseOptions::create_multimap_unsized::<str,str>())
  .unwrap();
let txn = lmdb::WriteTransaction::new(&env).unwrap();
{
  let mut access = txn.access();
  access.put(&db, "Fruit", "Apple", lmdb::put::Flags::empty()).unwrap();
  access.put(&db, "Fruit", "Orange", lmdb::put::Flags::empty()).unwrap();
  assert_eq!("Apple", access.get::<str,str>(&db, "Fruit").unwrap());
  access.del_key(&db, "Fruit").unwrap();
  assert!(access.get::<str,str>(&db, "Fruit").is_err());
}
txn.commit().unwrap();

pub fn del_item<K: AsLmdbBytes + ?Sized, V: AsLmdbBytes + ?Sized>(
    &mut self,
    db: &Database,
    key: &K,
    val: &V
) -> Result<()>

Delete items from a database by key and value.

This function removes key/data pairs from the database. If the database does not support sorted duplicate data items (DUPSORT) the val parameter is ignored and this call behaves like del(). Otherwise, if the data item matching both key and val will be deleted. This function will return NOTFOUND if the specified key/data pair is not in the database.

Example

let db = lmdb::Database::open(
  &env, Some("example"),
  &lmdb::DatabaseOptions::create_multimap_unsized::<str,str>())
  .unwrap();
let txn = lmdb::WriteTransaction::new(&env).unwrap();
{
  let mut access = txn.access();
  access.put(&db, "Fruit", "Apple", lmdb::put::Flags::empty()).unwrap();
  access.put(&db, "Fruit", "Orange", lmdb::put::Flags::empty()).unwrap();
  assert_eq!("Apple", access.get::<str,str>(&db, "Fruit").unwrap());
  access.del_item(&db, "Fruit", "Apple").unwrap();
  assert_eq!("Orange", access.get::<str,str>(&db, "Fruit").unwrap());
}
txn.commit().unwrap();

pub fn clear_db(&mut self, db: &Database) -> Result<()>

Completely clears the content of the given database.

Example

let txn = lmdb::WriteTransaction::new(&env).unwrap();
{
  let mut access = txn.access();
  let f = lmdb::put::Flags::empty();
  access.put(&db, "Germany", "Berlin", f).unwrap();
  access.put(&db, "France", "Paris", f).unwrap();
  access.put(&db, "Latvia", "Rīga", f).unwrap();
  assert_eq!(3, txn.db_stat(&db).unwrap().entries);

  access.clear_db(&db).unwrap();
  assert_eq!(0, txn.db_stat(&db).unwrap().entries);
}
txn.commit().unwrap();

Methods from Deref<Target = ConstAccessor<'txn>>

pub fn get<K: AsLmdbBytes + ?Sized, V: FromLmdbBytes + ?Sized>(
    &self,
    db: &Database,
    key: &K
) -> Result<&V>

Get items from a database.

This function retrieves key/data pairs from the database. A reference to the data associated with the given key is returned. If the database supports duplicate keys (DUPSORT) then the first data item for the key will be returned. Retrieval of other items requires the use of cursoring.

The returned memory is valid until the next mutation through the transaction or the end of the transaction (both are enforced through the borrow checker).

Errors

This call may return errors for reasons other than the key not being found. The easiest way to handle "not found" is generally to use the to_opt method on traits::LmdbResultExt to promote the value into a Result<Option<V>>. Most important of these other errors is the possibility of the key being found, but the value not being convertible to a &V.

Trait Implementations

impl<'txn> Debug for WriteAccessor<'txn>

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'txn> Deref for WriteAccessor<'txn>

type Target = ConstAccessor<'txn>

The resulting type after dereferencing.

fn deref(&self) -> &ConstAccessor<'txn>

Dereferences the value.