Struct KeyValueStoreView

pub struct KeyValueStoreView<C> { /* private fields */ }

A view that represents the functions of KeyValueStore.

Comment on the data set: In order to work, the view needs to store the updates and deleted prefixes. The updates and deleted prefixes have to be coherent. This means:

• If an index is deleted by one in deleted prefixes then it should not be present in the updates at all.
• DeletePrefix::key_prefix should not dominate anyone. That is if we have [0,2] then we should not have [0,2,3] since it would be dominated by the preceding.

With that we have:

• in order to test if an index is deleted by a prefix we compute the highest deleted prefix dp such that dp <= index. If dp is indeed a prefix then we conclude that index is deleted, otherwise not. The no domination is essential here.

Implementations

impl<C: Context> KeyValueStoreView<C>

pub fn total_size(&self) -> SizeData

Getting the total sizes that will be used for keys and values when stored

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![0, 1, 2, 3, 4]).await.unwrap();
let total_size = view.total_size();
assert_eq!(total_size, SizeData { key: 2, value: 5 });

pub async fn for_each_index_while<F>(&self, f: F) -> Result<(), ViewError>

where F: FnMut(&[u8]) -> Result<bool, ViewError> + Send,

Applies the function f over all indices. If the function f returns false, then the loop ends prematurely.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![0]).await.unwrap();
view.insert(vec![0, 2], vec![0]).await.unwrap();
view.insert(vec![0, 3], vec![0]).await.unwrap();
let mut count = 0;
view.for_each_index_while(|_key| {
    count += 1;
    Ok(count < 2)
})
.await
.unwrap();
assert_eq!(count, 2);

pub async fn for_each_index<F>(&self, f: F) -> Result<(), ViewError>

where F: FnMut(&[u8]) -> Result<(), ViewError> + Send,

Applies the function f over all indices.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![0]).await.unwrap();
view.insert(vec![0, 2], vec![0]).await.unwrap();
view.insert(vec![0, 3], vec![0]).await.unwrap();
let mut count = 0;
view.for_each_index(|_key| {
    count += 1;
    Ok(())
})
.await
.unwrap();
assert_eq!(count, 3);

pub async fn for_each_index_value_while<F>(&self, f: F) -> Result<(), ViewError>

where F: FnMut(&[u8], &[u8]) -> Result<bool, ViewError> + Send,

Applies the function f over all index/value pairs. If the function f returns false then the loop ends prematurely.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![0]).await.unwrap();
view.insert(vec![0, 2], vec![0]).await.unwrap();
let mut values = Vec::new();
view.for_each_index_value_while(|_key, value| {
    values.push(value.to_vec());
    Ok(values.len() < 1)
})
.await
.unwrap();
assert_eq!(values, vec![vec![0]]);

pub async fn for_each_index_value<F>(&self, f: F) -> Result<(), ViewError>

where F: FnMut(&[u8], &[u8]) -> Result<(), ViewError> + Send,

Applies the function f over all index/value pairs.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![0]).await.unwrap();
view.insert(vec![0, 2], vec![0]).await.unwrap();
let mut part_keys = Vec::new();
view.for_each_index_while(|key| {
    part_keys.push(key.to_vec());
    Ok(part_keys.len() < 1)
})
.await
.unwrap();
assert_eq!(part_keys, vec![vec![0, 1]]);

pub async fn indices(&self) -> Result<Vec<Vec<u8>>, ViewError>

Returns the list of indices in lexicographic order.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![0]).await.unwrap();
view.insert(vec![0, 2], vec![0]).await.unwrap();
let indices = view.indices().await.unwrap();
assert_eq!(indices, vec![vec![0, 1], vec![0, 2]]);

pub async fn index_values(&self) -> Result<Vec<(Vec<u8>, Vec<u8>)>, ViewError>

Returns the list of indices and values in lexicographic order.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![0]).await.unwrap();
view.insert(vec![0, 2], vec![0]).await.unwrap();
let key_values = view.indices().await.unwrap();
assert_eq!(key_values, vec![vec![0, 1], vec![0, 2]]);

pub async fn count(&self) -> Result<usize, ViewError>

Returns the number of entries.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![0]).await.unwrap();
view.insert(vec![0, 2], vec![0]).await.unwrap();
let count = view.count().await.unwrap();
assert_eq!(count, 2);

pub async fn get(&self, index: &[u8]) -> Result<Option<Vec<u8>>, ViewError>

Obtains the value at the given index, if any.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![42]).await.unwrap();
assert_eq!(view.get(&[0, 1]).await.unwrap(), Some(vec![42]));
assert_eq!(view.get(&[0, 2]).await.unwrap(), None);

pub async fn contains_key(&self, index: &[u8]) -> Result<bool, ViewError>

Tests whether the store contains a specific index.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![42]).await.unwrap();
assert!(view.contains_key(&[0, 1]).await.unwrap());
assert!(!view.contains_key(&[0, 2]).await.unwrap());

pub async fn contains_keys( &self, indices: &[Vec<u8>], ) -> Result<Vec<bool>, ViewError>

Tests whether the view contains a range of indices

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![42]).await.unwrap();
let keys = vec![vec![0, 1], vec![0, 2]];
let results = view.contains_keys(&keys).await.unwrap();
assert_eq!(results, vec![true, false]);

pub async fn multi_get( &self, indices: &[Vec<u8>], ) -> Result<Vec<Option<Vec<u8>>>, ViewError>

Obtains the values of a range of indices

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![42]).await.unwrap();
assert_eq!(
    view.multi_get(&[vec![0, 1], vec![0, 2]]).await.unwrap(),
    vec![Some(vec![42]), None]
);

pub async fn write_batch(&mut self, batch: Batch) -> Result<(), ViewError>

Applies the given batch of crate::common::WriteOperation.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![34]).await.unwrap();
view.insert(vec![3, 4], vec![42]).await.unwrap();
let mut batch = Batch::new();
batch.delete_key_prefix(vec![0]);
view.write_batch(batch).await.unwrap();
let key_values = view.find_key_values_by_prefix(&[0]).await.unwrap();
assert_eq!(key_values, vec![]);

pub async fn insert( &mut self, index: Vec<u8>, value: Vec<u8>, ) -> Result<(), ViewError>

Sets or inserts a value.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![34]).await.unwrap();
assert_eq!(view.get(&[0, 1]).await.unwrap(), Some(vec![34]));

pub async fn remove(&mut self, index: Vec<u8>) -> Result<(), ViewError>

Removes a value. If absent then the action has no effect.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![34]).await.unwrap();
view.remove(vec![0, 1]).await.unwrap();
assert_eq!(view.get(&[0, 1]).await.unwrap(), None);

pub async fn remove_by_prefix( &mut self, key_prefix: Vec<u8>, ) -> Result<(), ViewError>

Deletes a key prefix.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![34]).await.unwrap();
view.remove_by_prefix(vec![0]).await.unwrap();
assert_eq!(view.get(&[0, 1]).await.unwrap(), None);

pub async fn find_keys_by_prefix( &self, key_prefix: &[u8], ) -> Result<Vec<Vec<u8>>, ViewError>

Iterates over all the keys matching the given prefix. The prefix is not included in the returned keys.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![34]).await.unwrap();
view.insert(vec![3, 4], vec![42]).await.unwrap();
let keys = view.find_keys_by_prefix(&[0]).await.unwrap();
assert_eq!(keys, vec![vec![1]]);

pub async fn find_key_values_by_prefix( &self, key_prefix: &[u8], ) -> Result<Vec<(Vec<u8>, Vec<u8>)>, ViewError>

Iterates over all the key-value pairs, for keys matching the given prefix. The prefix is not included in the returned keys.

let mut view = KeyValueStoreView::load(context).await.unwrap();
view.insert(vec![0, 1], vec![34]).await.unwrap();
view.insert(vec![3, 4], vec![42]).await.unwrap();
let key_values = view.find_key_values_by_prefix(&[0]).await.unwrap();
assert_eq!(key_values, vec![(vec![1], vec![34])]);

Trait Implementations

impl<C> Allocative for KeyValueStoreView<C>

fn visit<'allocative_a, 'allocative_b: 'allocative_a>( &self, visitor: &'allocative_a mut Visitor<'allocative_b>, )

impl<C: Context> ClonableView for KeyValueStoreView<C>

fn clone_unchecked(&mut self) -> Result<Self, ViewError>

Creates a clone of this view, sharing the underlying storage context but prone to data races which can corrupt the view state.

impl<C: Debug> Debug for KeyValueStoreView<C>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<C: Context> HashableView for KeyValueStoreView<C>

type Hasher = CoreWrapper<Sha3_256Core>

How to compute hashes.

async fn hash_mut( &mut self, ) -> Result<<Self::Hasher as Hasher>::Output, ViewError>

Same as hash but guaranteed to be wait-free.

async fn hash(&self) -> Result<<Self::Hasher as Hasher>::Output, ViewError>

Computes the hash of the values.

impl<C: Context, C2: Context> ReplaceContext<C2> for KeyValueStoreView<C>

type Target = KeyValueStoreView<C2>

The type returned after replacing the context.

async fn with_context( &mut self, ctx: impl FnOnce(&Self::Context) -> C2 + Clone, ) -> Self::Target

Returns a view with a replaced context.

impl<C: Context> View for KeyValueStoreView<C>

const NUM_INIT_KEYS: usize = 2usize

The number of keys used for the initialization

type Context = C

The type of context stored in this view

fn context(&self) -> C

Obtains a mutable reference to the internal context.

fn pre_load(context: &C) -> Result<Vec<Vec<u8>>, ViewError>

Creates the keys needed for loading the view

fn post_load(context: C, values: &[Option<Vec<u8>>]) -> Result<Self, ViewError>

Loads a view from the values

fn rollback(&mut self)

Discards all pending changes. After that flush should have no effect to storage.

async fn has_pending_changes(&self) -> bool

Returns true if flushing this view would result in changes to the persistent storage.

fn pre_save(&self, batch: &mut Batch) -> Result<bool, ViewError>

Computes the batch of operations to persist changes to storage without modifying the view. Crash-resistant storage implementations accumulate the desired changes in the batch variable. The returned boolean indicates whether the operation removes the view or not.

fn post_save(&mut self)

Updates the view state after the batch has been executed in the database. This should be called after pre_save and after the batch has been successfully written to storage. This leaves the view in a clean state with no pending changes.

fn clear(&mut self)

Clears the view. That can be seen as resetting to default. If the clear is followed by a flush then all the relevant data is removed on the storage.

fn load( context: Self::Context, ) -> impl Future<Output = Result<Self, ViewError>> + Send + Sync

Loads a view

fn new(context: Self::Context) -> Result<Self, ViewError>

Builds a trivial view that is already deleted