Struct bastion::context::BastionContext

pub struct BastionContext { /* fields omitted */ }

A child's execution context, allowing its [exec] future to receive messages and access a ChildRef referencing it, a ChildrenRef referencing its children group and a SupervisorRef referencing its supervisor.

Example

Bastion::children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            // Get a `ChildRef` referencing the child executing
            // this future...
            let current: &ChildRef = ctx.current();
            // Get a `ChildrenRef` referencing the children
            // group of the child executing this future...
            let parent: &ChildrenRef = ctx.parent();
            // Try to get a `SupervisorRef` referencing the
            // supervisor of the child executing this future...
            let supervisor: Option<&SupervisorRef> = ctx.supervisor();
            // Note that `supervisor` will be `None` because
            // this child was created using `Bastion::children`,
            // which made it supervised by the system supervisor
            // (which users can't get a reference to).

            // Try to receive a message...
            let opt_msg: Option<Msg> = ctx.try_recv().await;
            // Wait for a message to be received...
            let msg: Msg = ctx.recv().await?;

            Ok(())
        }
    })
}).expect("Couldn't create the children group.");

Methods

impl BastionContext

pub fn current(&self) -> &ChildRef

Returns a ChildRef referencing the children group's element that is linked to this BastionContext.

Example

Bastion::children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            let current: &ChildRef = ctx.current();
            // Stop or kill the current element (note that this will
            // only take effect after this future becomes "pending")...

            Ok(())
        }
    })
}).expect("Couldn't create the children group.");

pub fn parent(&self) -> &ChildrenRef

Returns a ChildrenRef referencing the children group of the element that is linked to this BastionContext.

Example

Bastion::children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            let parent: &ChildrenRef = ctx.parent();
            // Get the other elements of the group, broadcast message,
            // or stop or kill the children group...

            Ok(())
        }
    })
}).expect("Couldn't create the children group.");

pub fn supervisor(&self) -> Option<&SupervisorRef>

Returns a SupervisorRef referencing the supervisor that supervises the element that is linked to this BastionContext if it isn't the system supervisor (ie. if the children group wasn't created using Bastion::children).

Example

// When calling the method from a children group supervised
// by a supervisor created by the user...
Bastion::supervisor(|sp| {
    sp.children(|children| {
        children.with_exec(|ctx: BastionContext| {
            async move {
                // ...the method will return a SupervisorRef referencing the
                // user-created supervisor...
                let supervisor: Option<&SupervisorRef> = ctx.supervisor(); // Some
                assert!(supervisor.is_some());

                Ok(())
            }
        })
    })
}).expect("Couldn't create the supervisor.");

// When calling the method from a children group supervised
// by the system's supervisor...
Bastion::children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            // ...the method won't return a SupervisorRef...
            let supervisor: Option<&SupervisorRef> = ctx.supervisor(); // None
            assert!(supervisor.is_none());

            Ok(())
        }
    })
}).expect("Couldn't create the children group.");

pub async fn try_recv<'_>(&'_ self) -> Option<Msg>

Tries to retrieve asynchronously a message received by the element this BastionContext is linked to.

If you need to wait (always asynchronously) until at least one message can be retrieved, use recv instead.

This method returns Msg if a message was available, or `None otherwise.

Example

Bastion::children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            let opt_msg: Option<Msg> = ctx.try_recv().await;
            // If a message was received by the element, `opt_msg` will
            // be `Some(Msg)`, otherwise it will be `None`.

            Ok(())
        }
    })
}).expect("Couldn't create the children group.");

pub async fn recv<'_>(&'_ self) -> Result<Msg, ()>

Retrieves asynchronously a message received by the element this BastionContext is linked to and waits (always asynchronously) for one if none has been received yet.

If you don't need to wait until at least one message can be retrieved, use try_recv instead.

This method returns Msg if it succeeded, or Err(()) otherwise.

Example

Bastion::children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            // This will block until a message has been received...
            let msg: Msg = ctx.recv().await?;

            Ok(())
        }
    })
}).expect("Couldn't create the children group.");

Trait Implementations

impl Debug for BastionContext

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

Formats the value using the given formatter.