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