Struct PubSub 

pub struct PubSub<D> { /* private fields */ }

An in-process hierarchical-topic pub/sub message bus.

D is the payload type passed to subscribers. The bus is single-threaded and uses interior mutability, so subscribers may call back into the bus during synchronous delivery.

Implementations

impl<D> PubSub<D>

pub fn new() -> Self

Create an empty bus.

pub fn set_immediate_exceptions(&self, value: bool)

Set whether a panicking subscriber aborts delivery immediately.

Read fresh on each publish. Toggling it changes only later publishes.

pub fn immediate_exceptions(&self) -> bool

Current value of the immediate-exceptions flag.

pub fn subscribe<F>(&self, topic: impl Into<String>, func: F) -> Token

where F: Fn(&str, &D) + 'static,

Subscribe func to topic. Returns a Token for later removal.

Each call gets a fresh, unique token, even for the same callback on the same topic. The topic does not need to exist first.

pub fn subscribe_all<F>(&self, func: F) -> Token

where F: Fn(&str, &D) + 'static,

Subscribe func to the wildcard topic *. It then runs for every published message. Returns the token, like PubSub::subscribe.

pub fn subscribe_once<F>(&self, topic: impl Into<String>, func: F) -> Token

where F: Fn(&str, &D) + 'static,

Subscribe func to fire at most once.

Delivery removes the entry before it calls func. A republish of the same topic from inside func does not retrigger it.

pub fn publish(&self, topic: impl Into<String>, data: D) -> bool

Publish data to topic for deferred delivery.

Queues delivery and returns at once. Subscribers run on the next PubSub::process_deferred call. Returns true if the topic had at least one matching subscriber when this was called.

pub fn publish_sync(&self, topic: impl Into<String>, data: D) -> bool

Publish data to topic and deliver to all matching subscribers now.

Returns true if there was at least one matching subscriber, else false. The return value is computed before any subscriber runs.

pub fn process_deferred(&self)

Run the deliveries queued by PubSub::publish so far, in call order.

This stands in for one event loop tick. It drains the jobs queued before the call. A subscriber that publishes during the drain queues its job for the next call, not this one. Call again to drain those.

Under delayed exceptions a panicking subscriber does not stop the other jobs in the batch. Every job runs, then the first panic is re-raised after the batch drains. Under immediate exceptions the first panic propagates at once and the rest of the batch does not run.

pub fn pending(&self) -> usize

Number of queued deferred deliveries.

pub fn unsubscribe(&self, token: &Token) -> Option<Token>

Remove the single subscription identified by token.

Returns the token if it matched a live subscription, else None. A second removal of the same token returns None.

pub fn unsubscribe_topic(&self, topic: &str) -> bool

Remove a topic and every descendant topic, by string prefix.

Returns true if topic names an existing topic or a prefix of one, else false. Matching is a raw string prefix, not dot-boundary aware. unsubscribe_topic("a") therefore removes a, a.b, and ab alike.

pub fn clear_all_subscriptions(&self)

Empty the whole registry. Does not reset the token counter.

pub fn clear_subscriptions(&self, topic: &str)

Remove every topic whose name starts with topic (raw string prefix).

pub fn count_subscriptions(&self, topic: &str) -> usize

Count subscribers in the first registered topic whose name starts with topic, then stop.

This counts one topic, not the sum across the hierarchy. It stops at the first prefix match and returns that topic’s subscriber count.

pub fn get_subscriptions(&self, topic: &str) -> Vec<String>

List every registered topic name that starts with topic, in insertion order.

Trait Implementations

impl<D> Debug for PubSub<D>

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

Print topic names with their subscriber counts. Payloads and callbacks are never formatted, so D need not be Debug.

impl<D> Default for PubSub<D>

fn default() -> Self

Returns the “default value” for a type.