Struct bastion::supervisor::Supervisor

pub struct Supervisor { /* fields omitted */ }

A supervisor that can supervise both Children and other supervisors using a defined SupervisionStrategy (set with with_strategy or SupervisionStrategy::OneForOne by default).

When a supervised children group or supervisor faults, the supervisor will restart it and eventually some of its other supervised entities, depending on its supervision strategy.

Note that a supervisor, called the “system supervisor”, is created by the system at startup and is the supervisor supervising children groups created via Bastion::children.

Example

let sp_ref: SupervisorRef = Bastion::supervisor(|sp| {
    // Configure the supervisor...
    sp.with_strategy(SupervisionStrategy::OneForOne)
    // ...and return it.
}).expect("Couldn't create the supervisor.");

Implementations

impl Supervisor

pub fn id(&self) -> &BastionId

Returns this supervisor’s identifier.

Note that the supervisor’s identifier is reset when it is restarted.

Example

Bastion::supervisor(|sp| {
    let supervisor_id: &BastionId = sp.id();
    // ...
}).expect("Couldn't create the supervisor.");

pub fn supervisor<S>(self, init: S) -> Self where
    S: FnOnce(Supervisor) -> Supervisor, 

Creates a new supervisor, passes it through the specified init closure and then starts supervising it.

If you don’t need to chain calls to this Supervisor’s methods and need to get a SupervisorRef referencing the newly created supervisor, use the supervisor_ref method instead.

Arguments

• init - The closure taking the new supervisor as an argument and returning it once configured.

Example

parent.supervisor(|sp| {
    // Configure the supervisor...
    sp.with_strategy(SupervisionStrategy::OneForOne)
    // ...and return it.
})

pub fn supervisor_ref<S>(&mut self, init: S) -> SupervisorRef where
    S: FnOnce(Supervisor) -> Supervisor, 

Creates a new Supervisor, passes it through the specified init closure and then starts supervising it.

If you need to chain calls to this Supervisor’s methods and don’t need to get a SupervisorRef referencing the newly created supervisor, use the supervisor method instead.

Arguments

• init - The closure taking the new Supervisor as an argument and returning it once configured.

Example

let sp_ref: SupervisorRef = parent.supervisor_ref(|sp| {
    // Configure the supervisor...
    sp.with_strategy(SupervisionStrategy::OneForOne)
    // ...and return it.
});

pub fn children<C>(self, init: C) -> Self where
    C: FnOnce(Children) -> Children, 

Creates a new Children, passes it through the specified init closure and then starts supervising it.

If you don’t need to chain calls to this Supervisor’s methods and need to get a ChildrenRef referencing the newly created supervisor, use the children_ref method instead.

Arguments

• init - The closure taking the new Children as an argument and returning it once configured.

Example

sp.children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            // Send and receive messages...
            let opt_msg: Option<SignedMessage> = ctx.try_recv().await;

            // ...and return `Ok(())` or `Err(())` when you are done...
            Ok(())
            // Note that if `Err(())` was returned, the supervisor would
            // restart the children group.
        }
    })
})

pub fn children_ref<C>(&self, init: C) -> ChildrenRef where
    C: FnOnce(Children) -> Children, 

Creates a new Children, passes it through the specified init closure and then starts supervising it.

If you need to chain calls to this Supervisor’s methods and don’t need to get a ChildrenRef referencing the newly created supervisor, use the children method instead.

Arguments

• init - The closure taking the new Children as an argument and returning it once configured.

Example

let children_ref: ChildrenRef = sp.children_ref(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            // Send and receive messages...
            let opt_msg: Option<SignedMessage> = ctx.try_recv().await;

            // ...and return `Ok(())` or `Err(())` when you are done...
            Ok(())
            // Note that if `Err(())` was returned, the supervisor would
            // restart the children group.
        }
    })
});

pub fn with_strategy(self, strategy: SupervisionStrategy) -> Self

Sets the strategy the supervisor should use when one of its supervised children groups or supervisors dies (in the case of a children group, it could be because one of its elements panicked or returned an error).

The default strategy is SupervisionStrategy::OneForOne.

Arguments

• strategy - The strategy to use:
  • SupervisionStrategy::OneForOne would only restart the supervised children groups or supervisors that fault.
  • SupervisionStrategy::OneForAll would restart all the supervised children groups or supervisors (even those which were stopped) when one of them faults, respecting the order in which they were added.
  • SupervisionStrategy::RestForOne would restart the supervised children groups or supervisors that fault along with all the other supervised children groups or supervisors that were added after them (even the stopped ones), respecting the order in which they were added.

Example

Bastion::supervisor(|sp| {
    // Note that "one-for-one" is the default strategy.
    sp.with_strategy(SupervisionStrategy::OneForOne)
}).expect("Couldn't create the supervisor");

pub fn with_restart_strategy(self, restart_strategy: RestartStrategy) -> Self

Sets the actor restart strategy the supervisor should use of its supervised children groups or supervisors dies to restore in the correct state.

The default strategy is the ActorRestartStrategy::Immediate and unlimited amount of retries.

Example

sp.with_restart_strategy(
    RestartStrategy::default()
        .with_restart_policy(RestartPolicy::Tries(5))
        .with_actor_restart_strategy(           
            ActorRestartStrategy::ExponentialBackOff {
                timeout: Duration::from_millis(5000),
                multiplier: 3.0,
            }
        )
)
}).expect("Couldn't create the supervisor");

pub fn with_callbacks(self, callbacks: Callbacks) -> Self

Sets the callbacks that will get called at this supervisor’s different lifecycle events.

See Callbacks’s documentation for more information about the different callbacks available.

Arguments

• callbacks - The callbacks that will get called for this supervisor.

Example

Bastion::supervisor(|sp| {
    let callbacks = Callbacks::new()
        .with_before_start(|| println!("Supervisor started."))
        .with_after_stop(|| println!("Supervisor stopped."));

    sp.with_callbacks(callbacks)
}).expect("Couldn't create the supervisor.");

Trait Implementations

impl Debug for Supervisor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.