Trait Component

pub trait Component {
    type AppState;

    // Required methods
    fn init_chain<'life0, 'async_trait, S>(
        state: S,
        app_state: Option<&'life0 Self::AppState>,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where S: 'async_trait + StateWrite,
             Self: 'async_trait,
             'life0: 'async_trait;
    fn begin_block<'life0, 'life1, 'async_trait, S>(
        state: &'life0 mut Arc<S>,
        begin_block: &'life1 BeginBlock,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where S: 'async_trait + StateWrite + 'static,
             'life0: 'async_trait,
             'life1: 'async_trait;
    fn end_block<'life0, 'life1, 'async_trait, S>(
        state: &'life0 mut Arc<S>,
        end_block: &'life1 EndBlock,
    ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>
       where S: 'async_trait + StateWrite + 'static,
             'life0: 'async_trait,
             'life1: 'async_trait;

    // Provided method
    fn end_epoch<'life0, 'async_trait, S>(
        _state: &'life0 mut Arc<S>,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where S: 'async_trait + StateWrite + 'static,
             'life0: 'async_trait { ... }
}

A component of a cnidarium-based application.

The use of &mut Arc<S> may seem unintuitive at first. However, it allows component implementations to optionally share state with concurrently-executing subtasks they spawn, without requiring additional locking. Components can clone the Arc and pass clones to concurrent, read-only subtasks, then later once the subtasks complete, use .get_mut() to obtain a mutable reference to the state.

Required Associated Types

type AppState

A serialized representation of the component’s application state, passed in to Component::init_chain.

Required Methods

fn init_chain<'life0, 'async_trait, S>( state: S, app_state: Option<&'life0 Self::AppState>, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where S: 'async_trait + StateWrite, Self: 'async_trait, 'life0: 'async_trait,

Performs initialization, given the genesis state.

This method is called once per chain, and should only perform writes, since the backing tree for the StateWrite will be empty.

If the app is checkpointed, no genesis app state will be passed in, and app_state will be None. Otherwise, app_state will be Some, indicating that the chain needs to fully initialize.

fn begin_block<'life0, 'life1, 'async_trait, S>( state: &'life0 mut Arc<S>, begin_block: &'life1 BeginBlock, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where S: 'async_trait + StateWrite + 'static, 'life0: 'async_trait, 'life1: 'async_trait,

Begins a new block, optionally inspecting the ABCI BeginBlock request.

Invariants

The &mut Arc<S> allows the implementor to optionally share state with its subtasks. The implementor SHOULD assume that when the method is called, state.get_mut().is_some(), i.e., the Arc is not shared. The implementor MUST ensure that any clones of the Arc are dropped before it returns, so that state.get_mut().is_some() on completion.

fn end_block<'life0, 'life1, 'async_trait, S>( state: &'life0 mut Arc<S>, end_block: &'life1 EndBlock, ) -> Pin<Box<dyn Future<Output = ()> + Send + 'async_trait>>

where S: 'async_trait + StateWrite + 'static, 'life0: 'async_trait, 'life1: 'async_trait,

Ends the block, optionally inspecting the ABCI EndBlock request, and performing any batch processing.

Invariants

This method should only be called after Component::begin_block. No methods should be called following this method.

The &mut Arc<S> allows the implementor to optionally share state with its subtasks. The implementor SHOULD assume that when the method is called, state.get_mut().is_some(), i.e., the Arc is not shared. The implementor MUST ensure that any clones of the Arc are dropped before it returns, so that state.get_mut().is_some() on completion.

Provided Methods

fn end_epoch<'life0, 'async_trait, S>( _state: &'life0 mut Arc<S>, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>

where S: 'async_trait + StateWrite + 'static, 'life0: 'async_trait,

Ends the epoch, applying component-specific state transitions that should occur when an epoch ends.

Note: epochs are not an ABCI concept. They are merely logical groups of blocks, defined by the application. Applications can choose to treat them as a no-op.

Invariants

The &mut Arc<S> allows the implementor to optionally share state with its subtasks. The implementor SHOULD assume that when the method is called, state.get_mut().is_some(), i.e., the Arc is not shared. The implementor MUST ensure that any clones of the Arc are dropped before it returns, so that state.get_mut().is_some() on completion.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors