Module casper_node::effect

Effects subsystem.

Effects describe things that the creator of the effect intends to happen, producing a value upon completion. They are, in fact, futures.

A pinned, boxed future returning an event is called an effect and typed as an Effect<Ev>, where Ev is the event's type. Generally, Ev is an Event enum defined at the top level of each component in the crate::components module.

Using effects

To create an effect, an EffectBuilder will be passed in from the relevant reactor. For example, given an effect builder effect_builder, we can create a set_timeout future and turn it into an effect:

use std::time::Duration;
use casper_node::effect::EffectExt;

enum Event {
    ThreeSecondsElapsed(Duration)
}

effect_builder
    .set_timeout(Duration::from_secs(3))
    .event(Event::ThreeSecondsElapsed);

This example will produce an effect that, after three seconds, creates an Event::ThreeSecondsElapsed. Note that effects do nothing on their own, they need to be passed to a reactor to be executed.

Arbitrary effects

While it is technically possible to turn any future into an effect, it is advisable to only use the effects explicitly listed in this module through traits to create them. Post-processing on effects to turn them into events should also be kept brief.

Announcements and effects

Some effects can be further classified into either announcements or requests, although these properties are not reflected in the type system.

Announcements are events emitted by components that are essentially "fire-and-forget"; the component will never expect an answer for these and does not rely on them being handled. It is also conceivable that they are being cloned and dispatched to multiple components by the reactor.

A good example is the arrival of a new deploy passed in by a client. Depending on the setup it may be stored, buffered or, in certain testing setups, just discarded. None of this is a concern of the component that talks to the client and deserializes the incoming deploy though, which considers the deploy no longer its concern after it has returned an announcement effect.

Requests are complex effects that are used when a component needs something from outside of itself (typically to be provided by another component); a request requires an eventual response.

A request must have a Responder field, which a handler of a request must call at some point. Failing to do so will result in a resource leak.

Modules

announcements	Announcement effects.
requests	Request effects.

Structs

EffectBuilder	A builder for Effects.
Responder	A responder satisfying a request.

Traits

EffectExt	Effect extension for futures, used to convert futures into actual effects.
EffectOptionExt	Effect extension for futures, used to convert futures returning an Option into two different effects.
EffectResultExt	Effect extension for futures, used to convert futures returning a Result into two different effects.

Type Definitions

Effect	A pinned, boxed future that produces one or more events.
Effects	Multiple effects in a container.