Struct WriteTransaction

Source

pub struct WriteTransaction<'a> { /* private fields */ }

Expand description

A single-writer (serialized) cross-partition transaction

Use WriteTransaction::commit to commit changes to the partition(s).

Drop the transaction to rollback changes.

Implementations§

Source §

impl<'a> WriteTransaction<'a>

Source

pub fn durability(self, mode: Option<PersistMode>) -> Self

Sets the durability level.

Source

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

Removes an item and returns its value if it existed.

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

let mut tx = keyspace.write_tx();

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

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

§Errors

Will return Err if an IO error occurs.

Source

pub fn update_fetch<K: Into<UserKey>, F: FnMut(Option<&UserValue>) -> Option<UserValue>>( &mut self, partition: &TxPartitionHandle, 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.

§Examples

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

let mut tx = keyspace.write_tx();

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

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

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

let mut tx = keyspace.write_tx();

let updated = tx.update_fetch(&partition, "a", |_| None)?;
assert!(updated.is_none());
tx.commit()?;

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

§Errors

Will return Err if an IO error occurs.

Source

pub fn fetch_update<K: Into<UserKey>, F: FnMut(Option<&UserValue>) -> Option<UserValue>>( &mut self, partition: &TxPartitionHandle, 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.

§Examples

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

let mut tx = keyspace.write_tx();

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

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

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

let mut tx = keyspace.write_tx();

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

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

§Errors

Will return Err if an IO error occurs.

Source

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

Retrieves an item from the transaction’s state.

The transaction allows reading your own writes (RYOW).

§Examples

partition.insert("a", "previous_value")?;
assert_eq!(b"previous_value", &*partition.get("a")?.unwrap());

let mut tx = keyspace.write_tx();
tx.insert(&partition, "a", "new_value");

// Read-your-own-write
let item = tx.get(&partition, "a")?;
assert_eq!(Some("new_value".as_bytes().into()), item);

drop(tx);

// Write was not committed
assert_eq!(b"previous_value", &*partition.get("a")?.unwrap());

§Errors

Will return Err if an IO error occurs.

Source

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

Retrieves an item from the transaction’s state.

The transaction allows reading your own writes (RYOW).

§Examples

partition.insert("a", "previous_value")?;
assert_eq!(b"previous_value", &*partition.get("a")?.unwrap());

let mut tx = keyspace.write_tx();
tx.insert(&partition, "a", "new_value");

// Read-your-own-write
let len = tx.size_of(&partition, "a")?.unwrap_or_default();
assert_eq!("new_value".len() as u32, len);

drop(tx);

// Write was not committed
assert_eq!(b"previous_value", &*partition.get("a")?.unwrap());

§Errors

Will return Err if an IO error occurs.

Source

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

Returns true if the transaction’s state contains the specified key.

§Examples

partition.insert("a", "my_value")?;
assert!(keyspace.read_tx().contains_key(&partition, "a")?);

let mut tx = keyspace.write_tx();
assert!(tx.contains_key(&partition, "a")?);

tx.insert(&partition, "b", "my_value2");
assert!(tx.contains_key(&partition, "b")?);

// Transaction not committed yet
assert!(!keyspace.read_tx().contains_key(&partition, "b")?);

tx.commit()?;
assert!(keyspace.read_tx().contains_key(&partition, "b")?);

§Errors

Will return Err if an IO error occurs.

Source

pub fn first_key_value( &self, partition: &TxPartitionHandle, ) -> Result<Option<KvPair>>

Returns the first key-value pair in the transaction’s state. The key in this pair is the minimum key in the transaction’s state.

§Examples

let mut tx = keyspace.write_tx();
tx.insert(&partition, "1", "abc");
tx.insert(&partition, "3", "abc");
tx.insert(&partition, "5", "abc");

let (key, _) = tx.first_key_value(&partition)?.expect("item should exist");
assert_eq!(&*key, "1".as_bytes());

assert!(keyspace.read_tx().first_key_value(&partition)?.is_none());

§Errors

Will return Err if an IO error occurs.

Source

pub fn last_key_value( &self, partition: &TxPartitionHandle, ) -> Result<Option<KvPair>>

Returns the last key-value pair in the transaction’s state. The key in this pair is the maximum key in the transaction’s state.

§Examples

let mut tx = keyspace.write_tx();
tx.insert(&partition, "1", "abc");
tx.insert(&partition, "3", "abc");
tx.insert(&partition, "5", "abc");

let (key, _) = tx.last_key_value(&partition)?.expect("item should exist");
assert_eq!(&*key, "5".as_bytes());

assert!(keyspace.read_tx().last_key_value(&partition)?.is_none());

§Errors

Will return Err if an IO error occurs.

Source

pub fn len(&self, partition: &TxPartitionHandle) -> Result<usize>

Scans the entire partition, returning the amount of items.

§Examples

partition.insert("a", "my_value")?;
partition.insert("b", "my_value2")?;

let mut tx = keyspace.write_tx();
assert_eq!(2, tx.len(&partition)?);

tx.insert(&partition, "c", "my_value3");

// read-your-own write
assert_eq!(3, tx.len(&partition)?);

// Transaction is not committed yet
assert_eq!(2, keyspace.read_tx().len(&partition)?);

tx.commit()?;
assert_eq!(3, keyspace.read_tx().len(&partition)?);

§Errors

Will return Err if an IO error occurs.

Source

pub fn iter<'b>( &'b self, partition: &TxPartitionHandle, ) -> impl DoubleEndedIterator<Item = Result<KvPair>> + 'b

Iterates over the transaction’s state.

Avoid using this function, or limit it as otherwise it may scan a lot of items.

§Examples

let mut tx = keyspace.write_tx();
tx.insert(&partition, "a", "abc");
tx.insert(&partition, "f", "abc");
tx.insert(&partition, "g", "abc");

assert_eq!(3, tx.iter(&partition).count());
assert_eq!(0, keyspace.read_tx().iter(&partition).count());

Source

pub fn keys<'b>( &'b self, partition: &TxPartitionHandle, ) -> impl DoubleEndedIterator<Item = Result<UserKey>> + 'b

Iterates over the transaction’s state, returning keys only.

Avoid using this function, or limit it as otherwise it may scan a lot of items.

Source

pub fn values<'b>( &'b self, partition: &TxPartitionHandle, ) -> impl DoubleEndedIterator<Item = Result<UserValue>> + 'b

Iterates over the transaction’s state, returning values only.

Avoid using this function, or limit it as otherwise it may scan a lot of items.

Source

pub fn range<'b, K: AsRef<[u8]> + 'b, R: RangeBounds<K> + 'b>( &'b self, partition: &'b TxPartitionHandle, range: R, ) -> impl DoubleEndedIterator<Item = Result<KvPair>> + 'b

Avoid using full or unbounded ranges as they may scan a lot of items (unless limited).

§Examples

let mut tx = keyspace.write_tx();
tx.insert(&partition, "a", "abc");
tx.insert(&partition, "f", "abc");
tx.insert(&partition, "g", "abc");

assert_eq!(2, tx.range(&partition, "a"..="f").count());
assert_eq!(0, keyspace.read_tx().range(&partition, "a"..="f").count());

Source

pub fn prefix<'b, K: AsRef<[u8]> + 'b>( &'b self, partition: &'b TxPartitionHandle, prefix: K, ) -> impl DoubleEndedIterator<Item = Result<KvPair>> + 'b

Iterates over a prefixed set of the transaction’s state.

Avoid using an empty prefix as it may scan a lot of items (unless limited).

§Examples

let mut tx = keyspace.write_tx();
tx.insert(&partition, "a", "abc");
tx.insert(&partition, "ab", "abc");
tx.insert(&partition, "abc", "abc");

assert_eq!(2, tx.prefix(&partition, "ab").count());
assert_eq!(0, keyspace.read_tx().prefix(&partition, "ab").count());

Source

pub fn insert<K: Into<UserKey>, V: Into<UserValue>>( &mut self, partition: &TxPartitionHandle, key: K, value: V, )

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.

§Examples

partition.insert("a", "previous_value")?;
assert_eq!(b"previous_value", &*partition.get("a")?.unwrap());

let mut tx = keyspace.write_tx();
tx.insert(&partition, "a", "new_value");

drop(tx);

// Write was not committed
assert_eq!(b"previous_value", &*partition.get("a")?.unwrap());

§Errors

Will return Err if an IO error occurs.

Source

pub fn remove<K: Into<UserKey>>( &mut self, partition: &TxPartitionHandle, key: K, )

Removes an item from the partition.

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

§Examples

partition.insert("a", "previous_value")?;
assert_eq!(b"previous_value", &*partition.get("a")?.unwrap());

let mut tx = keyspace.write_tx();
tx.remove(&partition, "a");

// Read-your-own-write
let item = tx.get(&partition, "a")?;
assert_eq!(None, item);

drop(tx);

// Deletion was not committed
assert_eq!(b"previous_value", &*partition.get("a")?.unwrap());