Struct sled_extensions::structured::Tree

pub struct Tree<V, E>(_, _, _, _);

A flash-sympathetic persistent lock-free B+ tree

Methods

impl<V, E> StructuredTree<V, E> where
    E: Encoding<V> + 'static, 

pub fn cloned(&self) -> Self

Clone for structures where V and E aren't Clone

pub fn transaction<F, R>(&self, f: F) -> TransactionResult<Result<R>> where
    F: Fn(StructuredTransactionalTree<V, E>) -> TransactionResult<Result<R>>, 

Perform a multi-key serializable transaction.

Transactions also work on tuples of Trees, preserving serializable ACID semantics! In this example, we treat two trees like a work queue, atomically apply updates to data and move them from the unprocessed Tree to the processed Tree.

pub fn apply_batch(&self, batch: StructuredBatch<V, E>) -> Result<()>

Create a new batched update that can be atomically applied.

It is possible to apply a Batch in a transaction as well, which is the way you can apply a Batch to multiple Trees atomically.

pub fn cas<K>(
    &self,
    key: K,
    old: Option<V>,
    new: Option<V>
) -> Result<Result<(), Option<V>>> where
    K: AsRef<[u8]>, 

Compare and swap. Capable of unique creation, conditional modification, or deletion. If old is None, this will only set the value if it doesn't exist yet. If new is None, will delete the value if old is correct. If both old and new are Some, will modify the value if old is correct. If Tree is read-only, will do nothing.

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

Retrieve a value from the Tree if it exists.

pub fn insert<K>(&self, key: K, value: V) -> Result<Option<V>> where
    IVec: From<K>,
    K: AsRef<[u8]>, 

Insert a key to a new value, returning the last value if it was set.

pub fn remove<K>(&self, key: K) -> Result<Option<V>> where
    K: AsRef<[u8]>, 

Delete a value, returning the old value if it existed.

pub fn update_and_fetch<K>(
    &self,
    key: K,
    f: impl Fn(Option<V>) -> Option<V>
) -> Result<Option<V>> where
    K: AsRef<[u8]>, 

Fetch the value, apply a function to it and return the result.

Note

This may call the function multiple times if the value has been changed from other threads in the meantime.

pub fn fetch_and_update<K>(
    &self,
    key: K,
    f: impl Fn(Option<V>) -> Option<V>
) -> Result<Option<V>> where
    K: AsRef<[u8]>, 

Fetch the value, apply a function to it and return the previous value.

Note

This may call the function multiple times if the value has been changed from other threads in the meantime.

pub fn watch_prefix(&self, prefix: Vec<u8>) -> Subscriber

Subscribe to Events that happen to keys that have the specified prefix. Events for particular keys are guaranteed to be witnessed in the same order by all threads, but threads may witness different interleavings of Events across different keys. If subscribers don't keep up with new writes, they will cause new writes to block. There is a buffer of 1024 items per Subscriber. This can be used to build reactive and replicated systems.

pub fn flush(&self) -> Result<()>

Synchronously flushes all dirty IO buffers and calls fsync. If this succeeds, it is guaranteed that all previous writes will be recovered if the system crashes. Returns the number of bytes flushed during this call.

Flushing can take quite a lot of time, and you should measure the performance impact of using it on realistic sustained workloads running on realistic hardware.

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

Returns true if the Tree contains a value for the specified key.

Important traits for StructuredIter<V, E>

impl<V, E> Iterator for StructuredIter<V, E> where
    E: Encoding<V>,  type Item = Result<(IVec, V)>;

pub fn iter(&self) -> StructuredIter<V, E>

Create a double-ended iterator over the tuples of keys and values in this tree.

Important traits for StructuredIter<V, E>

impl<V, E> Iterator for StructuredIter<V, E> where
    E: Encoding<V>,  type Item = Result<(IVec, V)>;

pub fn range<K, R>(&self, range: R) -> StructuredIter<V, E> where
    K: AsRef<[u8]>,
    R: RangeBounds<K>, 

Create a double-ended iterator over tuples of keys and values, where the keys fall within the specified range.

pub fn get_lt<K>(&self, key: K) -> Result<Option<(IVec, V)>> where
    K: AsRef<[u8]>, 

Retrieve the key and value before the provided key, if one exists.

pub fn get_gt<K>(&self, key: K) -> Result<Option<(IVec, V)>> where
    K: AsRef<[u8]>, 

Retrieve the next key and value from the Tree after the provided key.

Note

The order follows the Ord implementation for Vec:

[] < [0] < [255] < [255, 0] < [255, 255] ...

To retain the ordering of numerical types use big endian reprensentation

Important traits for StructuredIter<V, E>

impl<V, E> Iterator for StructuredIter<V, E> where
    E: Encoding<V>,  type Item = Result<(IVec, V)>;

pub fn scan_prefix<P>(&self, prefix: P) -> StructuredIter<V, E> where
    P: AsRef<[u8]>, 

Create an iterator over tuples of keys and values, where the all the keys starts with the given prefix.

pub fn pop_max(&self) -> Result<Option<(IVec, V)>>

Atomically removes the maximum item in the Tree instance.

pub fn pop_min(&self) -> Result<Option<(IVec, V)>>

Atomically removes the minimum item in the Tree instance.

pub fn len(&self) -> usize

Returns the number of elements in this tree.

Beware: performs a full O(n) scan under the hood.

pub fn is_empty(&self) -> bool

Returns true if the Tree contains no elements.

pub fn clear(&self) -> Result<()>

Clears the Tree, removing all values.

Note that this is not atomic.

pub fn name(&self) -> String

Returns the name of the tree.

Trait Implementations

impl<V: Clone, E: Clone> Clone for StructuredTree<V, E>

fn clone(&self) -> StructuredTree<V, E>

Returns a copy of the value.

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

Performs copy-assignment from source.