Struct bastion::children::Children

pub struct Children { /* fields omitted */ }

A children group that will contain a defined number of elements (set with with_redundancy or 1 by default) all running a future (returned by the closure that is set with with_exec).

When an element of the group stops or panics, all the elements will be stopped as well and the group's supervisor will receive a notice that a stop or panic occurred (note that if a panic occurred, the supervisor will restart the children group and eventually some of its other children, depending on its SupervisionStrategy).

Example

let children_ref: ChildrenRef = Bastion::children(|children| {
    // Configure the children group...
    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.
        }
    })
    // ...and return it.
}).expect("Couldn't create the children group.");

Implementations

impl Children

pub fn id(&self) -> &BastionId

Returns this children group's identifier.

Note that the children group's identifier is reset when it is restarted.

Example

Bastion::children(|children| {
    let children_id: &BastionId = children.id();
    // ...
}).expect("Couldn't create the children group.");

pub fn with_name(self, name: impl Into<String>) -> Self

Sets the name of this children group.

pub fn with_exec<I, F>(self, init: I) -> Self where
    I: Fn(BastionContext) -> F + Send + 'static,
    F: Future<Output = Result<(), ()>> + Send + 'static, 

Sets the closure taking a BastionContext and returning a Future that will be used by every element of this children group.

When a new element is started, it will be assigned a new context, pass it to the init closure and poll the returned future until it stops, panics or another element of the group stops or panics.

The returned future's output should be Result<(), ()>.

Arguments

• init - The closure taking a BastionContext and returning a Future that will be used by every element of this children group.

Example

Bastion::children(|children| {
    children.with_exec(|ctx| {
        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.
        }
    })
}).expect("Couldn't create the children group.");

pub fn with_redundancy(self, redundancy: usize) -> Self

Sets the number of elements this children group will contain. Each element will call the closure passed in with_exec and run the returned future until it stops, panics or another element in the group stops or panics.

The default number of elements a children group contains is 1.

Arguments

• redundancy - The number of elements this group will contain.

Example

Bastion::children(|children| {
    // Note that "1" is the default number of elements.
    children.with_redundancy(1)
}).expect("Couldn't create the children group.");

pub fn with_dispatcher(self, dispatcher: Dispatcher) -> Self

Appends each supervised element to the declared dispatcher.

By default supervised elements aren't added to any of dispatcher.

Arguments

• redundancy - An instance of struct that implements the DispatcherHandler trait.

Example

Bastion::children(|children| {
    children
        .with_dispatcher(
            Dispatcher::with_type(DispatcherType::Named("CustomGroup".to_string()))
        )
}).expect("Couldn't create the children group.");

pub fn with_resizer(self, resizer: OptimalSizeExploringResizer) -> Self

Sets a custom resizer for the Children.

This method is available only with the scaling feature flag.

Arguments

• resizer - An instance of the Resizer struct.

Example

Bastion::children(|children| {
    children
        .with_resizer(
            OptimalSizeExploringResizer::default()
                .with_lower_bound(10)
                .with_upper_bound(UpperBound::Limit(100))
        )
}).expect("Couldn't create the children group.");

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

Sets the callbacks that will get called at this children group'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 children group.

Example

Bastion::children(|children| {
    let callbacks = Callbacks::new()
        .with_before_start(|| println!("Children group started."))
        .with_after_stop(|| println!("Children group stopped."));

    children
        .with_callbacks(callbacks)
        .with_exec(|ctx| {
            // -- Children group started.
            async move {
                // ...
            }
            // -- Children group stopped.
        })
}).expect("Couldn't create the children group.");

pub fn with_heartbeat_tick(self, interval: Duration) -> Self

Overrides the default time interval for heartbeat onto the user defined.

Arguments

• interval - The value of the std::time::Duration type

Example

Bastion::children(|children| {
    children
        .with_heartbeat_tick(Duration::from_secs(5))
        .with_exec(|ctx| {
            // -- Children group started.
            async move {
                // ...
            }
            // -- Children group stopped.
        })
}).expect("Couldn't create the children group.");

Trait Implementations

impl Debug for Children

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

Formats the value using the given formatter.