bbolt_rs

Trait DbApi

Source 
pub trait DbApi:
    Clone
    + Send
    + Sync
where
    Self: Sized,
{
    // Required methods
    fn begin(&self) -> Result<impl TxApi<'_>>;
    fn view<'tx, F: FnMut(TxRef<'tx>) -> Result<()>>(
        &'tx self,
        f: F,
    ) -> Result<()>;
    fn stats(&self) -> Arc<DbStats>;
    fn path(&self) -> &DbPath;
    fn info(&self) -> DbInfo;
    fn close(self);
}
Expand description

Read-only DB API

Required Methods§

Source

fn begin(&self) -> Result<impl TxApi<'_>>

Begin 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.

IMPORTANT: You must drop the read-only transactions after you are finished or else the database will not reclaim old pages.

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(())
  })?;

  let tx = db.begin()?;
  let b = tx.bucket("test").unwrap();
  assert_eq!(Some(b"value".as_ref()), b.get("key"));

  Ok(())
}
Source

fn view<'tx, F: FnMut(TxRef<'tx>) -> Result<()>>(&'tx self, f: F) -> Result<()>

View executes a function within the context of a managed read-only transaction. Any error that is returned from the function is returned from the View() 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(())
}
Source

fn stats(&self) -> Arc<DbStats>

Stats retrieves ongoing performance stats for the database.

This is only updated when a transaction closes.

Source

fn path(&self) -> &DbPath

Returns the database’s path

use bbolt_rs::*;

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

  assert_eq!(&DbPath::Memory, db.path());
  Ok(())
}
Source

fn info(&self) -> DbInfo

Returns the database internal information

use bbolt_rs::*;

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

  assert_eq!(page_size::get(), db.info().page_size);
  Ok(())
}
Source

fn close(self)

Close releases all database resources.

It will block waiting for any open transactions to finish before closing the database and returning.

Once closed, other instances return Error::DatabaseNotOpen

use bbolt_rs::*;

fn main() -> Result<()> {
  let mut db = Bolt::open_mem()?;
  let cloned = db.clone();
  db.update(|mut tx| {
    let mut b = tx.create_bucket_if_not_exists("test")?;
    b.put("key", "value")?;
    Ok(())
  })?;

  db.close();
  assert_eq!(Some(Error::DatabaseNotOpen), cloned.begin().err());
  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§