Struct cnidarium::StateDelta

pub struct StateDelta<S: StateRead> { /* private fields */ }

An arbitrarily-deeply nested stack of delta updates to an underlying state.

This API allows exploring a tree of possible execution paths concurrently, before finally selecting one and applying it to the underlying state.

Using this API requires understanding its invariants.

On creation, StateDelta::new takes ownership of a StateRead + StateWrite instance, acquiring a “write lock” over the underlying state (since &mut S is StateWrite if S: StateWrite, it’s possible to pass a unique reference).

The resulting StateDelta instance is a “leaf” state, and can be used for reads and writes, following the some execution path.

When two potential execution paths diverge, delta.fork() can be used to fork the state update. The new forked StateDelta will include all previous state writes made to the original (and its ancestors). Any writes made to the original StateDelta after fork() is called will not be seen by the forked state.

Finally, after some execution path has been selected, calling delta.apply() on one of the possible state updates will commit the changes to the underlying state instance, and invalidate all other delta updates in the same family. It is a programming error to use the other delta updates after apply() has been called, but ideally this should not be a problem in practice: the API is intended to explore a tree of possible execution paths; once one has been selected, the others should be discarded.

Implementations

impl<S: StateRead> StateDelta<S>

pub fn new(state: S) -> Self

Create a new tree of possible updates to an underlying state.

pub fn fork(&mut self) -> Self

Fork execution, returning a new child state that includes all previous changes.

pub fn flatten(self) -> (S, Cache)

Flatten all changes in this branch of the tree into a single Cache, invalidating all other branches of the tree and releasing the underlying state back to the caller.

The apply method is a convenience wrapper around this that applies the changes to the underlying state.

impl<S: StateRead + StateWrite> StateDelta<S>

pub fn apply(self) -> (S, Vec<Event>)

Apply all changes in this branch of the tree to the underlying state, releasing it back to the caller and invalidating all other branches of the tree.

impl<S: StateRead + StateWrite> StateDelta<Arc<S>>

pub fn try_apply(self) -> Result<(S, Vec<Event>)>

Trait Implementations

impl<S: Debug + StateRead> Debug for StateDelta<S>

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

Formats the value using the given formatter.

impl<S: StateRead> StateRead for StateDelta<S>

type GetRawFut = CacheFuture<<S as StateRead>::GetRawFut>

type PrefixRawStream = StateDeltaPrefixRawStream<<S as StateRead>::PrefixRawStream>

type PrefixKeysStream = StateDeltaPrefixKeysStream<<S as StateRead>::PrefixKeysStream>

type NonconsensusPrefixRawStream = StateDeltaNonconsensusPrefixRawStream<<S as StateRead>::NonconsensusPrefixRawStream>

type NonconsensusRangeRawStream = StateDeltaNonconsensusRangeRawStream<<S as StateRead>::NonconsensusRangeRawStream>

fn get_raw(&self, key: &str) -> Self::GetRawFut

Gets a value from the verifiable key-value store as raw bytes.

fn nonverifiable_get_raw(&self, key: &[u8]) -> Self::GetRawFut

Gets a byte value from the non-verifiable key-value store.

fn object_type(&self, key: &'static str) -> Option<TypeId>

Gets the [TypeId] of the object stored at key in the ephemeral key-object store, if any is present.

fn object_get<T: Any + Send + Sync + Clone>( &self, key: &'static str ) -> Option<T>

Gets an object from the ephemeral key-object store.

fn prefix_raw(&self, prefix: &str) -> Self::PrefixRawStream

Retrieve all values for keys matching a prefix from the verifiable key-value store, as raw bytes.

fn prefix_keys(&self, prefix: &str) -> Self::PrefixKeysStream

Retrieve all keys (but not values) matching a prefix from the verifiable key-value store.

fn nonverifiable_prefix_raw( &self, prefix: &[u8] ) -> Self::NonconsensusPrefixRawStream

Retrieve all values for keys matching a prefix from the non-verifiable key-value store, as raw bytes.

fn nonverifiable_range_raw( &self, prefix: Option<&[u8]>, range: impl RangeBounds<Vec<u8>> ) -> Result<Self::NonconsensusRangeRawStream>

Retrieve all values for keys in a range from the non-verifiable key-value store, as raw bytes. This method does not support inclusive ranges, and will return an error if passed one.

impl<S: StateRead> StateWrite for StateDelta<S>

fn put_raw(&mut self, key: String, value: OwnedValue)

Puts raw bytes into the verifiable key-value store with the given key.

fn delete(&mut self, key: String)

Delete a key from the verifiable key-value store.

fn nonverifiable_delete(&mut self, key: Vec<u8>)

Delete a key from non-verifiable key-value storage.

fn nonverifiable_put_raw(&mut self, key: Vec<u8>, value: Vec<u8>)

Puts raw bytes into the non-verifiable key-value store with the given key.

fn object_put<T: Clone + Any + Send + Sync>( &mut self, key: &'static str, value: T )

Puts an object into the ephemeral object store with the given key.

fn object_delete(&mut self, key: &'static str)

Deletes a key from the ephemeral object store.

fn object_merge( &mut self, objects: BTreeMap<&'static str, Option<Box<dyn Any + Send + Sync>>> )

Merge a set of object changes into this StateWrite.

fn record(&mut self, event: Event)

Record that an ABCI event occurred while building up this set of state changes.