Struct Snapshot

Source

pub struct Snapshot { /* private fields */ }

Expand description

A snapshot captures a read-only point-in-time view of the tree at the time the snapshot was created

As long as the snapshot is open, old versions of objects will not be evicted as to keep the snapshot consistent. Thus, snapshots should only be kept around for as little as possible.

Snapshots do not persist across restarts.

Implementations§

Source §

impl Snapshot

Source

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

Retrieves an item from the snapshot.

§Examples

use lsm_tree::{AbstractTree, Config, Tree};

let tree = Config::new(folder).open()?;
let snapshot = tree.snapshot(0);

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

let len = snapshot.size_of("a")?;
assert_eq!(None, len);

let snapshot = tree.snapshot(1);

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

let len = snapshot.size_of("b")?.unwrap_or_default();
assert_eq!(0, len);

§Errors

Will return Err if an IO error occurs.

Source

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

Retrieves an item from the snapshot.

§Examples

use lsm_tree::{AbstractTree, Config, Tree};

let tree = Config::new(folder).open()?;
let snapshot = tree.snapshot(0);

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

let item = snapshot.get("a")?;
assert_eq!(None, item);

let snapshot = tree.snapshot(1);

let item = snapshot.get("a")?.unwrap();
assert_eq!(b"my_value", &*item);

§Errors

Will return Err if an IO error occurs.

Source

pub fn iter(&self) -> impl DoubleEndedIterator<Item = Result<KvPair>> + 'static

Returns an iterator that scans through the entire snapshot.

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

§Examples

use lsm_tree::{AbstractTree, Config, Tree};

let tree = Config::new(folder).open()?;

tree.insert("a", "abc", 0);
tree.insert("f", "abc", 1);
let snapshot = tree.snapshot(2);

tree.insert("g", "abc", 2);

assert_eq!(2, snapshot.iter().count());

Source

pub fn keys(&self) -> impl DoubleEndedIterator<Item = Result<UserKey>> + 'static

Returns an iterator that scans through the entire snapshot, returning keys only.

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

§Examples

use lsm_tree::{AbstractTree, Config, Tree};

let tree = Config::new(folder).open()?;

tree.insert("a", "abc", 0);
tree.insert("f", "abc", 1);
let snapshot = tree.snapshot(2);

tree.insert("g", "abc", 2);

assert_eq!(2, snapshot.keys().count());

Source

pub fn values( &self, ) -> impl DoubleEndedIterator<Item = Result<UserValue>> + 'static

Returns an iterator that scans through the entire snapshot, returning values only.

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

§Examples

use lsm_tree::{AbstractTree, Config, Tree};

let tree = Config::new(folder).open()?;

tree.insert("a", "abc", 0);
tree.insert("f", "abc", 1);
let snapshot = tree.snapshot(2);

tree.insert("g", "abc", 2);

assert_eq!(2, snapshot.values().count());

Source

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

Returns an iterator over a range of items in the snapshot.

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

§Examples

use lsm_tree::{AbstractTree, Config, Tree};

let tree = Config::new(folder).open()?;

tree.insert("a", "abc", 0);
let snapshot = tree.snapshot(1);

tree.insert("f", "abc", 1);
tree.insert("g", "abc", 2);

assert_eq!(1, snapshot.range("a"..="f").count());

Source

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

Returns an iterator over a prefixed set of items in the snapshot.

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

§Examples

use lsm_tree::{AbstractTree, Config, Tree};

let tree = Config::new(folder).open()?;

tree.insert("a", "abc", 0);
tree.insert("ab", "abc", 1);
let snapshot = tree.snapshot(2);

tree.insert("abc", "abc", 2);

assert_eq!(2, snapshot.prefix("a").count());

Source

pub fn first_key_value(&self) -> Result<Option<(UserKey, UserValue)>>

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

§Examples

use lsm_tree::{AbstractTree, Config, Tree};

let tree = Config::new(folder).open()?;

tree.insert("5", "abc", 0);
tree.insert("3", "abc", 1);
let snapshot = tree.snapshot(2);

tree.insert("1", "abc", 2);

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

§Errors

Will return Err if an IO error occurs.

Source

pub fn last_key_value(&self) -> Result<Option<(UserKey, UserValue)>>

Returns the las key-value pair in the snapshot. The key in this pair is the maximum key in the snapshot.

§Examples

use lsm_tree::{AbstractTree, Config, Tree};

let tree = Config::new(folder).open()?;

tree.insert("1", "abc", 0);
tree.insert("3", "abc", 1);
let snapshot = tree.snapshot(2);

tree.insert("5", "abc", 2);

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

§Errors

Will return Err if an IO error occurs.

Source

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

Returns true if the snapshot contains the specified key.

§Examples

use lsm_tree::{AbstractTree, Config, Tree};

let tree = Config::new(folder).open()?;
let snapshot = tree.snapshot(0);

assert!(!snapshot.contains_key("a")?);

tree.insert("a", "abc", 0);
assert!(!snapshot.contains_key("a")?);

§Errors

Will return Err if an IO error occurs.

Source

pub fn is_empty(&self) -> Result<bool>

Returns true if the snapshot is empty.

This operation has O(1) complexity.

§Examples

use lsm_tree::{AbstractTree, Config, Tree};

let tree = Config::new(folder).open()?;
let snapshot = tree.snapshot(0);

assert!(snapshot.is_empty()?);

tree.insert("a", "abc", 0);
assert!(snapshot.is_empty()?);

§Errors

Will return Err if an IO error occurs.

Source

pub fn len(&self) -> Result<usize>

Scans the entire snapshot, returning the amount of items.

§Caution

This operation scans the entire tree: O(n) complexity!

Never, under any circumstances, use .len() == 0 to check if the snapshot is empty, use Snapshot::is_empty instead.

§Examples

use lsm_tree::{AbstractTree, Config, Tree};

let tree = Config::new(folder).open()?;
let snapshot = tree.snapshot(0);

assert_eq!(snapshot.len()?, 0);
tree.insert("1", "abc", 0);
tree.insert("3", "abc", 1);
tree.insert("5", "abc", 2);
assert_eq!(snapshot.len()?, 0);