Trait Stage

pub trait Stage<Provider>: Send + Sync {
    // Required methods
    fn id(&self) -> StageId;
    fn execute(
        &mut self,
        provider: &Provider,
        input: ExecInput,
    ) -> Result<ExecOutput, StageError>;
    fn unwind(
        &mut self,
        provider: &Provider,
        input: UnwindInput,
    ) -> Result<UnwindOutput, StageError>;

    // Provided methods
    fn poll_execute_ready(
        &mut self,
        _cx: &mut Context<'_>,
        _input: ExecInput,
    ) -> Poll<Result<(), StageError>> { ... }
    fn post_execute_commit(&mut self) -> Result<(), StageError> { ... }
    fn post_unwind_commit(&mut self) -> Result<(), StageError> { ... }
}

A stage is a segmented part of the syncing process of the node.

Each stage takes care of a well-defined task, such as downloading headers or executing transactions, and persist their results to a database.

Stages must have a unique ID and implement a way to “roll forwards” (Stage::execute) and a way to “roll back” (Stage::unwind).

Stages are executed as part of a pipeline where they are executed serially.

Stages receive DBProvider.

Required Methods

fn id(&self) -> StageId

Get the ID of the stage.

Stage IDs must be unique.

fn execute( &mut self, provider: &Provider, input: ExecInput, ) -> Result<ExecOutput, StageError>

Execute the stage. It is expected that the stage will write all necessary data to the database upon invoking this method.

fn unwind( &mut self, provider: &Provider, input: UnwindInput, ) -> Result<UnwindOutput, StageError>

Unwind the stage.

Provided Methods

fn poll_execute_ready( &mut self, _cx: &mut Context<'_>, _input: ExecInput, ) -> Poll<Result<(), StageError>>

Returns Poll::Ready(Ok(())) when the stage is ready to execute the given range.

This method is heavily inspired by tower’s Service trait. Any asynchronous tasks or communication should be handled in poll_execute_ready, e.g. moving downloaded items from downloaders to an internal buffer in the stage.

If the stage has any pending external state, then Poll::Pending is returned.

If Poll::Ready(Err(_)) is returned, the stage may not be able to execute anymore depending on the specific error. In that case, an unwind must be issued instead.

Once Poll::Ready(Ok(())) is returned, the stage may be executed once using execute. Until the stage has been executed, repeated calls to poll_execute_ready must return either Poll::Ready(Ok(())) or Poll::Ready(Err(_)).

Note that poll_execute_ready may reserve shared resources that are consumed in a subsequent call of execute, e.g. internal buffers. It is crucial for implementations to not assume that execute will always be invoked and to ensure that those resources are appropriately released if the stage is dropped before execute is called.

For the same reason, it is also important that any shared resources do not exhibit unbounded growth on repeated calls to poll_execute_ready.

Unwinds may happen without consulting poll_execute_ready first.

fn post_execute_commit(&mut self) -> Result<(), StageError>

Post execution commit hook.

This is called after the stage has been executed and the data has been committed by the provider. The stage may want to pass some data from Self::execute via the internal field.

fn post_unwind_commit(&mut self) -> Result<(), StageError>

Post unwind commit hook.

This is called after the stage has been unwound and the data has been committed by the provider. The stage may want to pass some data from Self::unwind via the internal field.

Implementations on Foreign Types

impl<Provider, T: Stage<Provider> + ?Sized> Stage<Provider> for Box<T>

where Box<T>: Send + Sync,

fn id(&self) -> StageId

fn poll_execute_ready( &mut self, _cx: &mut Context<'_>, _input: ExecInput, ) -> Poll<Result<(), StageError>>

fn execute( &mut self, provider: &Provider, input: ExecInput, ) -> Result<ExecOutput, StageError>

fn post_execute_commit(&mut self) -> Result<(), StageError>

fn unwind( &mut self, provider: &Provider, input: UnwindInput, ) -> Result<UnwindOutput, StageError>

fn post_unwind_commit(&mut self) -> Result<(), StageError>

Implementors

impl<Provider> Stage<Provider> for TestStage

Available on crate feature test-utils only.