Struct linera_views::views::key_value_store_view::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<'a, C> KeyValueStoreView<C>

where C: Send + Context + Sync, ViewError: From<C::Error>,

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();
let total_size = view.total_size();
assert_eq!(total_size, SizeData::default());

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<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<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![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> ClonableView<C> for KeyValueStoreView<C>

where C: Context + Send + Sync, ViewError: From<C::Error>,

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> HashableView<C> for KeyValueStoreView<C>

where C: Context + Send + Sync, ViewError: From<C::Error>,

type Hasher = CoreWrapper<Sha3_256Core>

How to compute hashes.

fn hash_mut<'life0, 'async_trait>( &'life0 mut self, ) -> Pin<Box<dyn Future<Output = Result<<Self::Hasher as Hasher>::Output, ViewError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Computes the hash of the values.

fn hash<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = Result<<Self::Hasher as Hasher>::Output, ViewError>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Computes the hash of the values.

impl<C> View<C> for KeyValueStoreView<C>

where C: Context + Send + Sync, ViewError: From<C::Error>,

const NUM_INIT_KEYS: usize = 2usize

The number of keys used for the initialization

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 load<'async_trait>( context: C, ) -> Pin<Box<dyn Future<Output = Result<Self, ViewError>> + Send + 'async_trait>>

where Self: 'async_trait,

Loads a view

fn rollback(&mut self)

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

fn has_pending_changes<'life0, 'async_trait>( &'life0 self, ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

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

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

Persists changes to storage. This leaves the view still usable and is essentially neutral to the program running. Crash-resistant storage implementations are expected to accumulate the desired changes in the batch variable first. If the view is dropped without calling flush, staged changes are simply lost. The returned boolean indicates whether the operation removes the view or not.

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 new(context: C) -> Result<Self, ViewError>

Builds a trivial view that is already deleted