Struct Host 

pub struct Host<M: MacBackend> { /* private fields */ }

Multi-identity orchestration layer for the node API.

Host owns the shared MAC run loop and routes inbound events to the correct LocalNode, including ephemeral PFS identities that belong to a long-term node. Applications typically:

1. construct a Host from a shared MacHandle
2. register one or more LocalNodes with add_node
3. attach callbacks to nodes / peers / wrappers
4. drive progress with run or pump_once

run() is the preferred long-lived driver. pump_once() exists for callers that need to multiplex UMSH progress with other async work using select!.

Callback re-entrancy

Receive and control callbacks (on_receive, on_text, on_ack_received, …) are invoked synchronously from inside pump_once while the coordinator borrow is held. A callback therefore MUST NOT call back into the MAC — it cannot await a send, and a blocking or re-entrant borrow of the coordinator would deadlock. Keep callbacks short and side-effect-free with respect to the MAC: record what you need (e.g. push to a queue or set a flag) and perform any follow-up sends after pump_once / run returns control to your own task.

Implementations

impl<M: MacBackend> Host<M>

pub fn new(mac: M) -> Self

Create a host around a shared MAC backend.

pub fn mac(&self) -> M

Return a clone of the underlying shared MAC backend.

pub fn pfs_control_options(&self) -> &SendOptions

Borrow the send options used for node-managed PFS control messages.

pub fn set_pfs_control_options(&mut self, options: SendOptions)

Replace the send options used for node-managed PFS control messages.

pub fn add_node(&mut self, identity_id: LocalIdentityId) -> LocalNode<M>

Create and register a LocalNode for an already-registered local identity.

The returned handle is cheap to clone and becomes the application-facing entry point for sending traffic and attaching callbacks for that identity.

pub fn node(&self, identity_id: LocalIdentityId) -> Option<LocalNode<M>>

Look up a previously added node by identity id.

pub async fn pump_once(&mut self) -> Result<(), HostError<M::RunError>>

Drive the shared MAC until one wake cycle completes.

This is a single wake-driven step, not a non-blocking poll. It waits until the MAC has meaningful work to do (radio activity or a protocol deadline), dispatches any resulting callbacks, services PFS command handling, and then returns.

Use this when you need to multiplex UMSH progress with other async sources using select!. If UMSH owns the task, prefer run.

pub async fn service_protocol_timeouts(&mut self)

Service node-layer deadlines independently of MAC/radio wake events.

A quiet radio is not a MAC wake source, so applications that multiplex pump_once with other work must also call this from their own timer. In particular, ping and PFS request timeouts must fire even when the remote peer sends no response at all.

pub fn protocol_timeout_servicer(&self) -> ProtocolTimeoutServicer<M>

where M: Clone,

Detach an owned handle that services the same node-layer deadlines as service_protocol_timeouts.

Use this when the host pump runs as its own long-lived future (so the Host is exclusively borrowed) and a sibling timer task must still fire ping/PFS timeouts — e.g. while the pump is parked awaiting a slow physical transmit. The handle snapshots the current node set; nodes added afterwards are not covered by it.

pub async fn run(&mut self) -> Result<(), HostError<M::RunError>>

Run the shared MAC/Host loop forever.

This is the preferred long-lived driver for node-based applications. It keeps the runtime wake policy inside the MAC/Host stack rather than requiring callers to write poll/sleep loops themselves.