Trait DbRwAPI

pub trait DbRwAPI: DbApi {
    // Required methods
    fn begin_rw(&mut self) -> Result<impl TxRwApi<'_>>;
    fn update<'tx, F: FnMut(TxRwRef<'tx>) -> Result<()>>(
        &'tx mut self,
        f: F,
    ) -> Result<()>;
    fn batch<F>(&mut self, f: F) -> Result<()>
       where F: FnMut(&mut TxRwRef<'_>) -> Result<()> + Send + Sync + Clone + 'static;
    fn sync(&mut self) -> Result<()>;
}

RW DB API

Required Methods

fn begin_rw(&mut self) -> Result<impl TxRwApi<'_>>

Starts a new transaction. Multiple read-only transactions can be used concurrently but only one write transaction can be used at a time. Starting multiple write transactions will cause the calls to block and be serialized until the current write transaction finishes.

Transactions should not be dependent on one another. Opening a read transaction and a write transaction in the same goroutine can cause the writer to deadlock because the database periodically needs to re-mmap itself as it grows and it cannot do that while a read transaction is open.

If a long running read transaction (for example, a snapshot transaction) is needed, you might want to set BoltOptions.initial_map_size to a large enough value to avoid potential blocking of write transaction.

Dropping the transaction will cause it to rollback.

use bbolt_rs::*;

fn main() -> Result<()> {
  let mut db = Bolt::open_mem()?;

  let mut tx = db.begin_rw()?;
  let mut b = tx.create_bucket_if_not_exists("test")?;
  b.put("key", "value")?;
  tx.commit()?;

  db.view(|tx| {
    let b = tx.bucket("test").unwrap();
    assert_eq!(Some(b"value".as_ref()), b.get("key"));
    Ok(())
  })?;

  Ok(())
}

fn update<'tx, F: FnMut(TxRwRef<'tx>) -> Result<()>>( &'tx mut self, f: F, ) -> Result<()>

Executes a function within the context of a read-write managed transaction.

If no error is returned from the function then the transaction is committed. If an error is returned then the entire transaction is rolled back. Any error that is returned from the function or returned from the commit is returned from the Update() method.

use bbolt_rs::*;

fn main() -> Result<()> {
  let mut db = Bolt::open_mem()?;

  db.update(|mut tx| {
    let mut b = tx.create_bucket_if_not_exists("test")?;
    b.put("key", "value")?;
    Ok(())
  })?;

  db.view(|tx| {
    let b = tx.bucket("test").unwrap();
    assert_eq!(Some(b"value".as_ref()), b.get("key"));
    Ok(())
  })?;

  Ok(())
}

fn batch<F>(&mut self, f: F) -> Result<()>

where F: FnMut(&mut TxRwRef<'_>) -> Result<()> + Send + Sync + Clone + 'static,

Calls a function as part of a batch. It behaves similar to Update, except:

1. concurrent Batch calls can be combined into a single Bolt transaction.

2. the function passed to Batch may be called multiple times, regardless of whether it returns error or not.

This means that Batch function side effects must be idempotent and take permanent effect only after a successful return is seen in caller.

The maximum batch size and delay can be adjusted with MaxBatchSize and MaxBatchDelay, respectively.

Batch is only useful when there are multiple threads calling it.

use bbolt_rs::*;

fn main() -> Result<()> {
  let mut db = Bolt::open_mem()?;

  db.batch(|mut tx| {
    let mut b = tx.create_bucket_if_not_exists("test")?;
    b.put("key", "value")?;
    Ok(())
  })?;

  db.view(|tx| {
    let b = tx.bucket("test").unwrap();
    assert_eq!(Some(b"value".as_ref()), b.get("key"));
    Ok(())
  })?;

  Ok(())
}

fn sync(&mut self) -> Result<()>

Executes fdatasync() against the database file handle.

This is not necessary under normal operation, however, if you use NoSync then it allows you to force the database file to sync against the disk.

use bbolt_rs::*;

fn main() -> Result<()> {
  let mut db = Bolt::open_mem()?;

  db.batch(|mut tx| {
    let mut b = tx.create_bucket_if_not_exists("test")?;
    b.put("key", "value")?;
    Ok(())
  })?;

  db.sync()?;

  Ok(())
}

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl DbRwAPI for Bolt