Struct bastion::child_ref::ChildRef

pub struct ChildRef { /* fields omitted */ }

A “reference” to an element of a children group, allowing to communicate with it.

Implementations

impl ChildRef

pub fn id(&self) -> &BastionId

Returns the identifier of the children group element this ChildRef is referencing.

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

Example

Bastion::children(|children| {
    children.with_exec(|ctx| {
        async move {
            let child_id: &BastionId = ctx.current().id();
            // ...
        }
    })
}).expect("Couldn't create the children group.");

pub fn is_public(&self) -> bool

Returns true if the child this ChildRef is referencing is public, Which means it can receive messages. private ChildRefs reference bastion internal children, such as the heartbeat child for example. This function comes in handy when implementing your own dispatchers.

Example

Bastion::children(|children| {
    children.with_exec(|ctx| {
        async move {
            if ctx.current().is_public() {
                // ...
            }
        }
    })
}).expect("Couldn't create the children group.");

pub fn tell_anonymously<M: Message>(&self, msg: M) -> Result<(), M>

Sends a message to the child this ChildRef is referencing. This message is intended to be used outside of Bastion context when there is no way for receiver to identify message sender

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

Argument

• msg - The message to send.

Example

// The message that will be "told"...
const TELL_MSG: &'static str = "A message containing data (tell).";

// Create a new child...
Bastion::children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            // ...which will receive the message "told"...
            msg! { ctx.recv().await?,
                msg: &'static str => {
                    assert_eq!(msg, TELL_MSG);
                    // Handle the message...
                };
                // This won't happen because this example
                // only "tells" a `&'static str`...
                _: _ => ();
            }

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

// Later, the message is "told" to the child...
child_ref.tell_anonymously(TELL_MSG).expect("Couldn't send the message.");

pub fn try_tell_anonymously<M: Message>(&self, msg: M) -> Result<(), SendError>

Try to send a message to the child this ChildRef is referencing. This message is intended to be used outside of Bastion context when there is no way for receiver to identify message sender

This method returns () if it succeeded, or a SendError(../child_ref/enum.SendError.html) otherwise.

Argument

• msg - The message to send.

Example

// The message that will be "told"...
const TELL_MSG: &'static str = "A message containing data (tell).";

// Create a new child...
Bastion::children(|children| {
    children.with_exec(|ctx: BastionContext| {
        async move {
            // ...which will receive the message "told"...
            msg! { ctx.recv().await?,
                msg: &'static str => {
                    assert_eq!(msg, TELL_MSG);
                    // Handle the message...
                };
                // This won't happen because this example
                // only "tells" a `&'static str`...
                _: _ => ();
            }

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

// Later, the message is "told" to the child...
child_ref.try_tell_anonymously(TELL_MSG).expect("Couldn't send the message.");

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

Sends a message to the child this ChildRef is referencing, allowing it to answer. This message is intended to be used outside of Bastion context when there is no way for receiver to identify message sender

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 = child_ref.ask_anonymously(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 try_ask_anonymously<M: Message>(
    &self,
    msg: M
) -> Result<Answer, SendError>

Try to send a message to the child this ChildRef is referencing, allowing it to answer. This message is intended to be used outside of Bastion context when there is no way for receiver to identify message sender

This method returns Answer if it succeeded, or a SendError(../child_ref/enum.SendError.html) 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 = child_ref.try_ask_anonymously(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 stop(&self) -> Result<(), ()>

Sends a message to the child this ChildRef is referencing to tell it to stop its execution.

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

Example

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

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

            Ok(())
        }
    })
}).expect("Couldn't create the children group.");
    child_ref.stop().expect("Couldn't send the message.");

pub fn kill(&self) -> Result<(), ()>

Sends a message to the child this ChildRef is referencing to tell it to suicide.

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

Example

child_ref.kill().expect("Couldn't send the message.");

pub fn addr(&self) -> RefAddr

Returns RefAddr for the child

pub fn path(&self) -> &Arc<BastionPath>

Returns the BastionPath of the child

pub fn name(&self) -> &str

Return the name of the child

Trait Implementations

impl Clone for ChildRef

fn clone(&self) -> ChildRef

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ChildRef

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

Formats the value using the given formatter.

impl Hash for ChildRef

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given Hasher.

impl PartialEq<ChildRef> for ChildRef

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl Eq for ChildRef