Struct LocalEventBus 

pub struct LocalEventBus { /* private fields */ }

Thread-safe in-process event bus.

This backend stores subscriptions in memory and dispatches subscriber handlers on background threads. Publishing schedules work and returns after dispatch, while wait_for_idle can be used by tests to wait for all handler work for a topic.

Implementations

impl LocalEventBus

pub fn new() -> Self

Creates a stopped local event bus.

Returns

A new event bus with no subscriptions.

pub fn started() -> EventBusResult<Self>

Creates and starts a local event bus.

Returns

A started event bus.

Errors

Returns startup errors from the handler executor.

pub fn start(&self) -> EventBusResult<bool>

Starts the event bus.

Returns

Ok(true) when this call changed the bus from stopped to started.

Errors

Returns startup errors from the handler executor.

pub fn shutdown(&self) -> bool

Shuts down the event bus.

The method waits for currently scheduled handlers to finish and then clears all subscriptions.

Returns

true when this call changed the bus from started to stopped.

Panics

Panics when called from one of this bus’s subscriber worker threads. A subscriber worker cannot wait for itself to finish. Use shutdown_nonblocking or shutdown_with_timeout from subscriber handlers.

pub fn shutdown_nonblocking(&self) -> bool

Requests shutdown without waiting for subscriber work to finish.

The bus stops accepting publish and subscribe operations, asks the handler executor to shut down, deactivates subscriptions, and returns immediately. Already running handler code is not interrupted.

Returns

true when this call changed the bus from started to stopped.

pub fn shutdown_with_timeout(&self, timeout: Duration) -> EventBusResult<bool>

Shuts down the event bus with a maximum wait duration.

The bus stops accepting new publish and subscribe operations immediately, then waits for scheduled subscriber work and executor workers to finish. If the timeout elapses, subscriptions are deactivated before the timeout error is returned.

Parameters

• timeout: Maximum duration to wait for graceful shutdown.

Returns

Ok(true) when this call changed the bus from started to stopped and shutdown completed within the timeout. Ok(false) means the bus was already stopped.

Errors

Returns EventBusError::ShutdownTimedOut if subscriber work or executor workers do not finish before timeout.

pub fn add_error_observer<F>(&self, observer: F) -> EventBusResult<()>

where F: Fn(&EventBusError) + Send + Sync + 'static,

Registers an observer for internal background errors.

Parameters

• observer: Callback invoked when interceptors, error handlers, or dead-letter routing fail.

Returns

Ok(()) when the observer is stored.

Errors

Returns a lock-poisoning error if observer state is unavailable.

pub fn publish<T>(&self, topic: &Topic<T>, payload: T) -> EventBusResult<()>

where T: Clone + Send + Sync + 'static,

Publishes a payload to a topic.

Parameters

• topic: Target topic.
• payload: Event payload.

Returns

Ok(()) after subscriber work has been scheduled.

Local dispatch is non-transactional across matching subscribers. If scheduling fails for a later subscriber, earlier subscriber work may already have been accepted.

Errors

Returns EventBusError::NotStarted if the bus is stopped.

pub fn publish_with_options<T>( &self, topic: &Topic<T>, payload: T, options: PublishOptions<T>, ) -> EventBusResult<()>

where T: Clone + Send + Sync + 'static,

Publishes a payload to a topic with explicit options.

Parameters

• topic: Target topic.
• payload: Event payload.
• options: Publish options merged with factory defaults.

Returns

Ok(()) after subscriber work has been scheduled.

Errors

Returns EventBusError::NotStarted if the bus is stopped.

pub fn publish_envelope<T>( &self, envelope: EventEnvelope<T>, ) -> EventBusResult<()>

where T: Clone + Send + Sync + 'static,

Publishes an existing envelope.

Parameters

• envelope: Event envelope to dispatch.

Returns

Ok(()) after subscriber work has been scheduled.

Errors

Returns EventBusError::NotStarted if the bus is stopped.

pub fn publish_envelope_with_options<T>( &self, envelope: EventEnvelope<T>, options: PublishOptions<T>, ) -> EventBusResult<()>

where T: Clone + Send + Sync + 'static,

Publishes an existing envelope with options.

Parameters

• envelope: Event envelope to dispatch.
• options: Publish options.

Returns

Ok(()) after subscriber work has been scheduled.

Errors

Returns EventBusError::NotStarted if the bus is stopped.

pub fn publish_all<T>( &self, envelopes: Vec<EventEnvelope<T>>, ) -> EventBusResult<BatchPublishResult>

where T: Clone + Send + Sync + 'static,

Publishes multiple envelopes by submitting each envelope in input order.

This method preserves submission order only. Handler execution order is backend-specific because local handlers can run on multiple worker threads.

Parameters

• envelopes: Envelopes to submit in order.

Returns

Summary containing per-envelope successes and failures.

Errors

Returns lifecycle or option validation errors before the batch starts.

pub fn publish_all_with_options<T>( &self, envelopes: Vec<EventEnvelope<T>>, options: PublishOptions<T>, ) -> EventBusResult<BatchPublishResult>

where T: Clone + Send + Sync + 'static,

Publishes multiple envelopes with explicit publish options.

Parameters

• envelopes: Envelopes to submit in order.
• options: Publish options cloned for each envelope.

Returns

Summary containing per-envelope successes and failures.

Errors

Returns lifecycle or option validation errors before the batch starts.

pub fn subscribe<T, S, F, R>( &self, subscriber_id: S, topic: &Topic<T>, handler: F, ) -> EventBusResult<Subscription<T>>

where T: Clone + Send + Sync + 'static, S: Into<String>, F: Fn(EventEnvelope<T>) -> R + Send + Sync + 'static, R: IntoEventBusResult + 'static,

Subscribes a handler using default options.

Parameters

• subscriber_id: Subscriber identifier.
• topic: Topic to subscribe.
• handler: Handler invoked for matching events.

Returns

Subscription handle.

Errors

Returns an error when the bus is stopped or shared state is unavailable.

pub fn subscribe_with_options<T, S, F, R>( &self, subscriber_id: S, topic: &Topic<T>, handler: F, options: SubscribeOptions<T>, ) -> EventBusResult<Subscription<T>>

where T: Clone + Send + Sync + 'static, S: Into<String>, F: Fn(EventEnvelope<T>) -> R + Send + Sync + 'static, R: IntoEventBusResult + 'static,

Subscribes a handler using explicit options.

Parameters

• subscriber_id: Subscriber identifier.
• topic: Topic to subscribe.
• handler: Handler invoked for matching events.
• options: Subscription processing options.

Returns

Subscription handle.

Errors

Returns an error when the bus is stopped, the subscriber ID is blank, or shared state is unavailable.

pub fn add_dead_letter_handler<F, R>( &self, dead_letter_topic: &Topic<DeadLetterPayload>, handler: F, options: SubscribeOptions<DeadLetterPayload>, ) -> EventBusResult<Subscription<DeadLetterPayload>>

where F: Fn(EventEnvelope<DeadLetterPayload>) -> R + Send + Sync + 'static, R: IntoEventBusResult + 'static,

Subscribes a handler to a dead-letter topic.

Dead-letter payloads are type-erased, so callers can inspect the original topic, error metadata, and original payload through DeadLetterPayload.

Parameters

• dead_letter_topic: Topic carrying dead-letter records.
• handler: Handler invoked for dead-letter events.
• options: Subscription options merged with factory defaults.

Returns

Subscription handle for the dead-letter topic.

Errors

Returns an error when the bus is stopped, the generated subscriber ID is invalid, or shared state is unavailable.

pub fn wait_for_idle<T>(&self, topic: &Topic<T>) -> EventBusResult<()>

where T: 'static,

Waits until all work for a topic is idle.

Parameters

• topic: Topic to wait for.

Returns

Ok(()) once the topic has no active handler work.

Errors

Returns a lock-poisoning error if tracker state is unavailable.

pub fn wait_for_idle_timeout<T>( &self, topic: &Topic<T>, timeout: Duration, ) -> EventBusResult<bool>

where T: 'static,

Waits until all work for a topic is idle or the timeout elapses.

Parameters

• topic: Topic to wait for.
• timeout: Maximum duration to wait.

Returns

Ok(true) once the topic has no active handler work, or Ok(false) when the timeout elapses first.

Errors

Returns a lock-poisoning error if tracker state is unavailable.

Trait Implementations

impl Clone for LocalEventBus

fn clone(&self) -> LocalEventBus

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for LocalEventBus

fn default() -> Self

Creates a stopped local event bus.

impl EventBus for LocalEventBus

fn start(&self) -> EventBusResult<bool>

Starts the local event bus.

fn shutdown(&self) -> bool

Shuts down the local event bus.

fn publish<T>(&self, topic: &Topic<T>, payload: T) -> EventBusResult<()>

where T: Clone + Send + Sync + 'static,

Publishes a payload using the local backend.

fn publish_with_options<T>( &self, topic: &Topic<T>, payload: T, options: PublishOptions<T>, ) -> EventBusResult<()>

where T: Clone + Send + Sync + 'static,

Publishes a payload with options using the local backend.

fn publish_envelope<T>(&self, envelope: EventEnvelope<T>) -> EventBusResult<()>

where T: Clone + Send + Sync + 'static,

Publishes an envelope using the local backend.

fn publish_envelope_with_options<T>( &self, envelope: EventEnvelope<T>, options: PublishOptions<T>, ) -> EventBusResult<()>

where T: Clone + Send + Sync + 'static,

Publishes an envelope with options using the local backend.

fn publish_all<T>( &self, envelopes: Vec<EventEnvelope<T>>, ) -> EventBusResult<BatchPublishResult>

where T: Clone + Send + Sync + 'static,

Publishes a batch using the local backend.

fn publish_all_with_options<T>( &self, envelopes: Vec<EventEnvelope<T>>, options: PublishOptions<T>, ) -> EventBusResult<BatchPublishResult>

where T: Clone + Send + Sync + 'static,

Publishes a batch with options using the local backend.

fn subscribe<T, S, F, R>( &self, subscriber_id: S, topic: &Topic<T>, handler: F, ) -> EventBusResult<Subscription<T>>

where T: Clone + Send + Sync + 'static, S: Into<String>, F: Fn(EventEnvelope<T>) -> R + Send + Sync + 'static, R: IntoEventBusResult + 'static,

Subscribes a handler using local backend defaults.

fn subscribe_with_options<T, S, F, R>( &self, subscriber_id: S, topic: &Topic<T>, handler: F, options: SubscribeOptions<T>, ) -> EventBusResult<Subscription<T>>

where T: Clone + Send + Sync + 'static, S: Into<String>, F: Fn(EventEnvelope<T>) -> R + Send + Sync + 'static, R: IntoEventBusResult + 'static,

Subscribes a handler with options using the local backend.

fn wait_for_idle<T>(&self, topic: &Topic<T>) -> EventBusResult<()>

where T: 'static,

Waits until local topic work is idle.

fn wait_for_idle_timeout<T>( &self, topic: &Topic<T>, timeout: Duration, ) -> EventBusResult<bool>

where T: 'static,

Waits until local topic work is idle or the timeout elapses.

fn add_dead_letter_handler<F, R>( &self, dead_letter_topic: &Topic<DeadLetterPayload>, handler: F, options: SubscribeOptions<DeadLetterPayload>, ) -> EventBusResult<Subscription<DeadLetterPayload>>

where F: Fn(EventEnvelope<DeadLetterPayload>) -> R + Send + Sync + 'static, R: IntoEventBusResult + 'static,

Registers a handler for standard dead-letter payloads.