Trait heph::supervisor::Supervisor

source · [−]
pub trait Supervisor<NA> where
    NA: NewActor, {
    fn decide(
        &mut self, 
        error: <NA::Actor as Actor>::Error
    ) -> SupervisorStrategy<NA::Argument>;
    fn decide_on_restart_error(
        &mut self, 
        error: NA::Error
    ) -> SupervisorStrategy<NA::Argument>;
    fn second_restart_error(&mut self, error: NA::Error);

    fn decide_on_panic(
        &mut self, 
        panic: Box<dyn Any + Send + 'static>
    ) -> SupervisorStrategy<NA::Argument> { ... }
}
Expand description

The supervisor of an actor.

For more information about supervisors see the module documentation, here only the design of the trait is discussed.

The trait is designed to be generic over the NewActor implementation (NA). This means that the same type can implement supervision for a number of different actors. But a word of caution, supervisors should generally be small and simple, which means that having a different supervisor for each actor is often a good thing.

The restart_supervisor! macro can be used to easily create a supervisor implementation that restarts the actor.

Supervisor can be implemented using a simple function if the NewActor implementation doesn’t return an error (i.e. NewActor::Error = !), which is the case for asynchronous functions. See the module documentation for an example of this.

Required Methods

Decide what happens to the actor that returned error.

Notes

A restarted actor will immediately will be scheduled run again. This has the benefit that the actor can setup any asynchronous operations without having to wait to be run again.

However it also has a downside: it’s easy to create create an error and restart loop. When a supervisor always restarts an actor that always returns an error, we’ve got an effective loop of restarting and running the actor, the actor crashes and is restarted and run again, etc.

To avoid creating such an loop limit the amount times an actor can be restarted. Or use the restart_supervisor! macro to automatically create a supervisor that handles this for you.

Decide what happens when an actor is restarted and the NewActor implementation returns an error.

Read the documentation of decide to avoid an infinite loop.

Method that gets call if an actor fails to restart twice.

This is only called if decide returns a restart strategy, the actors fails to restart, after which decide_on_restart_error is called and also returns a restart strategy and restarting the actor a second time also fails. We will not create an endless loop of restarting failures and instead call this function before stopping the actor (which can’t be restarted any more).

Provided Methods

Decide what happens to the actor that panicked.

This is similar to Supervisor::decide, but handles panics instead of errors (NewActor::Error).

Default

By default this stops the actor as a panic is always unexpected and is generally harder to recover from then an error.

Notes

The panic is always logged using the panic hook, in addition an error message is printed which states what actor panicked.

Implementors