Trait FromMessage

pub trait FromMessage<M>: Interface {
    type Response: MessageResponse;

    // Required method
    fn from_message(
        message: M,
        sender: <Self::Response as MessageResponse>::Sender,
    ) -> Self;
}

Declares a message as part of an Interface.

Messages have an associated Response type that determines the return value of sending the message. Within an interface, the responder can vary for each message. There are two provided responders.

No Response

NoResponse is used for fire-and-forget messages that do not return any values. These messages do not spawn futures and cannot be awaited. It is neither possible to verify whether the message was delivered to the service.

When implementing FromMessage for such messages, the second argument can be ignored by convention:

use relay_system::{FromMessage, Interface, NoResponse};

struct MyMessage;

enum MyInterface {
    MyMessage(MyMessage),
    // ...
}

impl Interface for MyInterface {}

impl FromMessage<MyMessage> for MyInterface {
    type Response = NoResponse;

    fn from_message(message: MyMessage, _: ()) -> Self {
        Self::MyMessage(message)
    }
}

Asynchronous Responses

AsyncResponse is used for messages that resolve to some future value. This value is sent back by the service through a Sender, which must be added into the interface:

use relay_system::{AsyncResponse, FromMessage, Interface, Sender};

struct MyMessage;

enum MyInterface {
    MyMessage(MyMessage, Sender<bool>),
    // ...
}

impl Interface for MyInterface {}

impl FromMessage<MyMessage> for MyInterface {
    type Response = AsyncResponse<bool>;

    fn from_message(message: MyMessage, sender: Sender<bool>) -> Self {
        Self::MyMessage(message, sender)
    }
}

Broadcast Responses

BroadcastResponse is similar to the previous asynchronous response, but it additionally allows to efficiently handle duplicate requests for services that debounce equivalent requests or cache results. On the requesting side, this behavior is identical to the asynchronous behavior, but it provides more utilities to the implementing service.

use relay_system::{BroadcastResponse, BroadcastSender, FromMessage, Interface};

struct MyMessage;

enum MyInterface {
    MyMessage(MyMessage, BroadcastSender<bool>),
    // ...
}

impl Interface for MyInterface {}

impl FromMessage<MyMessage> for MyInterface {
    type Response = BroadcastResponse<bool>;

    fn from_message(message: MyMessage, sender: BroadcastSender<bool>) -> Self {
        Self::MyMessage(message, sender)
    }
}

See Interface for more examples on how to build interfaces using this trait and Service documentation for patterns and advice to handle messages.

Required Associated Types

type Response: MessageResponse

The behavior declaring the return value when sending this message.

Required Methods

fn from_message( message: M, sender: <Self::Response as MessageResponse>::Sender, ) -> Self

Converts the message into the service interface.

Object Safety

This trait is not object safe.

Implementors