Struct bastion::context::BastionContext

pub struct BastionContext { /* fields omitted */ }

A child’s execution context, allowing its with_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<SignedMessage> = ctx.try_recv().await;
            // Wait for a message to be received...
            let msg: SignedMessage = ctx.recv().await?;

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

Implementations

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<SignedMessage>

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.

If you want to wait for a certain amount of time before bailing out use try_recv_timeout instead.

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

Example

Bastion::children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            let opt_msg: Option<SignedMessage> = 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<SignedMessage, ()>

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.

If you want to wait for a certain amount of time before bailing out use try_recv_timeout instead.

This method returns SignedMessage 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: SignedMessage = ctx.recv().await?;

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

pub async fn try_recv_timeout(
    &self,
    timeout: Duration
) -> Result<SignedMessage, ReceiveError>

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

If you want to wait for ever until at least one message can be retrieved, use recv instead.

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

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

Example

Bastion::children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            // This will block until a message has been received...
            let timeout = Duration::from_millis(10);
            let msg: SignedMessage = ctx.try_recv_timeout(timeout).await.map_err(|e| {
               if let ReceiveError::Timeout(duration) = e {
                   // Timeout happened      
               }
            })?;

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

pub fn signature(&self) -> RefAddr

Returns RefAddr of the current BastionContext

Example

Bastion::children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            ctx.tell(&ctx.signature(), "Hello to myself");

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

pub fn tell<M: Message>(&self, to: &RefAddr, msg: M) -> Result<(), M>

Sends a message to the specified RefAddr

Arguments

• to – the RefAddr to send the message to
• msg – The actual message to send

Example

Bastion::children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            // Wait for a message to be received...
            let smsg: SignedMessage = ctx.recv().await?;
            // Obtain address of this message sender...
            let sender_addr = smsg.signature();
            // And send something back
            ctx.tell(&sender_addr, "Ack").expect("Unable to acknowledge");
            Ok(())
        }
    })
}).expect("Couldn't create the children group.");

pub fn ask<M: Message>(&self, to: &RefAddr, msg: M) -> Result<Answer, M>

Sends a message from behalf of current context to the addr, allowing to addr owner answer.

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

Argument

• msg - The message to send.

Example

// The message that will be "asked"...
const ASK_MSG: &'static str = "A message containing data (ask).";
// The message the will be "answered"...
const ANSWER_MSG: &'static str = "A message containing data (answer).";

// Create a new child...
Bastion::children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            // ...which will receive the message asked...
            msg! { ctx.recv().await?,
                msg: &'static str =!> {
                    assert_eq!(msg, ASK_MSG);
                    // Handle the message...

                    // ...and eventually answer to it...
                    answer!(ctx, ANSWER_MSG);
                };
                // This won't happen because this example
                // only "asks" a `&'static str`...
                _: _ => ();
            }

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

// Later, the message is "asked" to the child...
let answer: Answer = ctx.ask(&child_ref.addr(), ASK_MSG).expect("Couldn't send the message.");

// ...and the child's answer is received...
msg! { answer.await.expect("Couldn't receive the answer."),
    msg: &'static str => {
        assert_eq!(msg, ANSWER_MSG);
        // Handle the answer...
    };
    // This won't happen because this example
    // only answers a `&'static str`...
    _: _ => ();
}

pub fn notify(
    &self,
    dispatchers: &[DispatcherType],
    notification_type: NotificationType
)

Sends the notification to each declared dispatcher of the actor.

Argument

• dispatchers - Vector of dispatcher names to which need to deliver a notification.
• notification_type - The type of the notification to send.

pub fn broadcast_message<M: Message>(&self, target: BroadcastTarget, message: M)

Sends the broadcasted message to the target group(s).

Argument

• target - Defines the message receivers in according with the BroadcastTarget value.
• message - The broadcasted message.

Trait Implementations

impl Debug for BastionContext

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

Formats the value using the given formatter.