Struct OptimisticTxKeyspace 

pub struct OptimisticTxKeyspace { /* private fields */ }

Handle to a keyspace of a transactional database

Implementations

impl OptimisticTxKeyspace

pub fn path(&self) -> PathBuf

Returns the underlying LSM-tree’s path.

pub fn approximate_len(&self) -> usize

Approximates the amount of items in the keyspace.

For update- or delete-heavy workloads, this value will diverge from the real value, but is a O(1) operation.

For insert-only workloads (e.g. logs, time series) this value is reliable.

Examples

assert_eq!(tree.approximate_len(), 0);

tree.insert("1", "abc")?;
assert_eq!(tree.approximate_len(), 1);

tree.remove("1")?;
// Oops! approximate_len will not be reliable here
assert_eq!(tree.approximate_len(), 2);

pub fn take<K: Into<UserKey>>(&self, key: K) -> Result<Option<UserValue>>

Removes an item and returns its value if it existed.

The operation will run wrapped in a transaction.

tree.insert("a", "abc")?;

let taken = tree.take("a")?.unwrap();
assert_eq!(b"abc", &*taken);

let item = tree.get("a")?;
assert!(item.is_none());

Errors

Will return Err if an IO error occurs.

pub fn fetch_update<K: Into<UserKey>, F: FnMut(Option<&UserValue>) -> Option<UserValue>>( &self, key: K, f: F, ) -> Result<Option<UserValue>>

Atomically updates an item and returns the previous value.

Returning None removes the item if it existed before.

The operation will run wrapped in a transaction.

Note

The provided closure can be called multiple times as this function automatically retries on conflict. Since this is an FnMut, make sure it is idempotent and will not cause side-effects.

Examples

tree.insert("a", "abc")?;

let prev = tree.fetch_update("a", |_| Some(Slice::from(*b"def")))?.unwrap();
assert_eq!(b"abc", &*prev);

let item = tree.get("a")?;
assert_eq!(Some("def".as_bytes().into()), item);

tree.insert("a", "abc")?;

let prev = tree.fetch_update("a", |_| None)?.unwrap();
assert_eq!(b"abc", &*prev);

let item = tree.get("a")?;
assert!(item.is_none());

Errors

Will return Err if an IO error occurs.

pub fn update_fetch<K: Into<UserKey>, F: FnMut(Option<&UserValue>) -> Option<UserValue>>( &self, key: K, f: F, ) -> Result<Option<UserValue>>

Atomically updates an item and returns the new value.

Returning None removes the item if it existed before.

The operation will run wrapped in a transaction.

Note

The provided closure can be called multiple times as this function automatically retries on conflict. Since this is an FnMut, make sure it is idempotent and will not cause side-effects.

Examples

tree.insert("a", "abc")?;

let updated = tree.update_fetch("a", |_| Some(Slice::from(*b"def")))?.unwrap();
assert_eq!(b"def", &*updated);

let item = tree.get("a")?;
assert_eq!(Some("def".as_bytes().into()), item);

tree.insert("a", "abc")?;

let updated = tree.update_fetch("a", |_| None)?;
assert!(updated.is_none());

let item = tree.get("a")?;
assert!(item.is_none());

Errors

Will return Err if an IO error occurs.

pub fn insert<K: Into<UserKey>, V: Into<UserValue>>( &self, key: K, value: V, ) -> Result<()>

Inserts a key-value pair into the keyspace.

Keys may be up to 65536 bytes long, values up to 2^32 bytes. Shorter keys and values result in better performance.

If the key already exists, the item will be overwritten.

The operation will run wrapped in a transaction.

Examples

tree.insert("a", "abc")?;

assert!(!db.read_tx().is_empty(&tree)?);

Errors

Will return Err if an IO error occurs.

pub fn remove<K: Into<UserKey>>(&self, key: K) -> Result<()>

Removes an item from the keyspace.

The key may be up to 65536 bytes long. Shorter keys result in better performance.

The operation will run wrapped in a transaction.

Examples

tree.insert("a", "abc")?;
assert!(!db.read_tx().is_empty(&tree)?);

tree.remove("a")?;
assert!(db.read_tx().is_empty(&tree)?);

Errors

Will return Err if an IO error occurs.

pub fn get<K: AsRef<[u8]>>(&self, key: K) -> Result<Option<UserValue>>

Retrieves an item from the keyspace.

The operation will run wrapped in a read snapshot.

Examples

tree.insert("a", "my_value")?;

let item = tree.get("a")?;
assert_eq!(Some("my_value".as_bytes().into()), item);

Errors

Will return Err if an IO error occurs.

pub fn size_of<K: AsRef<[u8]>>(&self, key: K) -> Result<Option<u32>>

Retrieves the size of an item from the keyspace.

The operation will run wrapped in a read snapshot.

Examples

tree.insert("a", "my_value")?;

let len = tree.size_of("a")?.unwrap_or_default();
assert_eq!("my_value".len() as u32, len);

Errors

Will return Err if an IO error occurs.

pub fn first_key_value(&self) -> Option<Guard>

Returns the first key-value pair in the keyspace. The key in this pair is the minimum key in the keyspace.

The operation will run wrapped in a read snapshot.

Examples

tree.insert("a", "my_value")?;
tree.insert("b", "my_value")?;

assert_eq!(b"a", &*tree.first_key_value().unwrap().key()?);

pub fn last_key_value(&self) -> Option<Guard>

Returns the last key-value pair in the keyspace. The key in this pair is the maximum key in the keyspace.

The operation will run wrapped in a read snapshot.

Examples

tree.insert("a", "my_value")?;
tree.insert("b", "my_value")?;

assert_eq!(b"b", &*tree.last_key_value().unwrap().key()?);

pub fn contains_key<K: AsRef<[u8]>>(&self, key: K) -> Result<bool>

Returns true if the keyspace contains the specified key.

The operation will run wrapped in a read snapshot.

Examples

tree.insert("a", "my_value")?;

assert!(tree.contains_key("a")?);
assert!(!tree.contains_key("b")?);

Errors

Will return Err if an IO error occurs.

Trait Implementations

impl AsRef<Keyspace> for OptimisticTxKeyspace

fn as_ref(&self) -> &Keyspace

Converts this type into a shared reference of the (usually inferred) input type.

impl Clone for OptimisticTxKeyspace

fn clone(&self) -> OptimisticTxKeyspace

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.