Struct ratman::Router

pub struct Router { /* fields omitted */ }

Primary async ratman router handle

Make sure you initialise endpoints before calling run, as the set of endpoints gets locked and can’t be changed during runtime.

Implementations

impl Router

pub fn new() -> Arc<Self>

Create a new and empty message router

It’s currently not possible to restore a router from stored state, which means that all routing tables are lost when the router is stopped.

pub async fn add_endpoint(
    &self,
    ep: Arc<impl Endpoint + 'static + Send + Sync>
) -> usize

Add a new endpoint to this router

An endpoint is defined by the Endpoint trait from the ratman-netmod crate. Once added, an endpoint can’t be removed while in active operation: the router will have to be recreated without the endpoint you wish to remove.

pub async fn del_endpoint(&self, id: usize)

Remove an endpoint from the router by ID

This function is primarily meant for testing purposes, and shouldn’t be used in heavy operation. The required ID is returned by add_endpoint.

pub async fn add_user(&self, id: Identity) -> Result<()>

Add an identity to the local set

Ratman will listen for messages to local identities and offer them up for polling via the Router API.

pub async fn del_user(&self, id: Identity, _keep: bool) -> Result<()>

Remove a local identity, discarding imcomplete messages

Ratman will by default remove all cached frames from the collector. Optionally these frames can be moved into the journal with low priority instead.

pub async fn online(&self, id: Identity) -> Result<()>

Set a user ID as online and broadcast announcements

This function will return an error if the user is already marked as online, or if no such user is known to the router

pub async fn offline(&self, id: Identity) -> Result<()>

Set a user ID as offline and stop broadcasts

pub async fn known(&self, id: Identity) -> Result<()>

Check the local routing table for a user ID

pub async fn discover(&self) -> Identity

Check for newly discovered users on the network

pub fn clock(&self, _cc: ClockCtrl<Tasks>) -> Result<()>

Register a manual clock controller object for internal tasks

pub async fn send(&self, msg: Message) -> Result<()>

Dispatch a message into a network

This operation completes asynchronously, and will yield a result with information about any error that occured while sending.

If you result is an Error::DispatchFaled, that just means that at least one of the packets your Message was sliced into didn’t send properly. As long as you’re not changing the data layout of your payload, or the MsgId, it’s safe to simply retry: the receiving collector/ journals on the way will still be able to associate the frames, and drop the ones that were already dispatched, essentially only filling in the missing gaps.

pub async fn next(&self) -> Message

Get the next available message from the router

Note: This function can’t ever really fail, because it only reads from a set of completed Messages that have been parsed and handled. When an error occurs on an incoming Message, the errors are logged in the diagnostics module, and can be read from there asynchronously.