Struct EventBus

Source

pub struct EventBus { /* private fields */ }

Expand description

EventBus - routes messages between components and channels.

The EventBus is responsible for:

Registering/unregistering Components
Routing Request messages to target Components
Broadcasting Signal messages to all Components
Injecting Events into specific Channels
Managing pending response channels

§Thread Safety

EventBus itself is not Send/Sync. Use it within a single async task or wrap with appropriate synchronization.

Implementations§

Source §

impl EventBus

Source

pub fn new() -> Self

Create new EventBus

Source

pub fn set_hook_registry(&mut self, registry: SharedHookRegistry)

Sets the shared hook registry for EventBus hooks.

Source

pub fn shared_handles(&self) -> SharedChannelHandles

Returns a clone of the shared channel handles.

This can be used by ClientRunner to broadcast events without holding a reference to the entire EventBus.

Source

pub fn shared_component_channel_map(&self) -> SharedComponentChannelMap

Returns a clone of the shared component-to-channel mapping.

Used by EventEmitter to resolve ComponentId → ChannelId for orcs.request() RPC routing.

Source

pub fn register( &mut self, id: ComponentId, subscriptions: Vec<EventCategory>, ) -> ComponentHandle

Register component with subscriptions.

The component will receive requests matching any of the specified categories when using publish for category-based routing.

§Arguments

id - Component identifier
subscriptions - Event categories this component subscribes to

§Example

let mut bus = EventBus::new();
let handle = bus.register(
    ComponentId::builtin("hil"),
    vec![EventCategory::Hil, EventCategory::Lifecycle],
);

Source

pub fn subscribers(&self, category: &EventCategory) -> Vec<&ComponentId>

Returns subscribers for a given category.

Source

pub fn unregister(&mut self, id: &ComponentId)

Unregister component

Source

pub async fn request(&mut self, req: Request) -> Result<Value, EngineError>

Send request to target component.

Routes the request to the specified target Component and waits for response. Target is required - use Request::with_target to set it.

§Errors

Returns EngineError if:

No target specified (EngineError::NoTarget)
Target component not found (EngineError::ComponentNotFound)
Send failed (EngineError::SendFailed)
Channel closed (EngineError::ChannelClosed)
Request timed out (EngineError::Timeout)

Source

pub async fn publish(&mut self, req: Request) -> Result<Value, EngineError>

Publish request to subscribers of the request’s category.

Routes the request to the first Component that subscribes to the request’s EventCategory. This enables loose coupling where the sender doesn’t need to know the specific target component.

§Category-Based Routing

Request { category: Hil, operation: "submit" }
    │
    ▼ (lookup subscribers for Hil)
EventBus::subscriptions[Hil] = [HilComponent]
    │
    ▼ (route to first subscriber)
HilComponent::on_request()

§Errors

Returns EngineError if:

No subscribers for the category (EngineError::NoSubscriber)
Send failed (EngineError::SendFailed)
Request timed out (EngineError::Timeout)

Source

pub fn respond(&mut self, request_id: RequestId, result: Result<Value, String>)

Respond to a pending request.

Components call this to complete a request with either a successful value or an error message. The error is wrapped as EngineError::ComponentFailed.

If the request_id is not found (already timed out or responded), this is a no-op.

Source

pub fn component_count(&self) -> usize

Get number of registered components

Source

pub fn register_channel(&mut self, handle: ChannelHandle)

Registers a channel handle for event injection.

Call this when a new ChannelRunner is created to enable event injection to that channel.

Source

pub fn register_component_channel( &mut self, component_id: &ComponentId, channel_id: ChannelId, )

Registers a Component FQN → ChannelId mapping for RPC routing.

After registration, request() will route requests targeting this Component through the ChannelHandle’s request channel instead of the standalone ComponentHandle path.

§Arguments

component_id - The Component’s identifier (FQN is extracted)
channel_id - The Channel hosting the Component

Source

pub fn unregister_channel(&mut self, id: &ChannelId)

Unregisters a channel handle.

Call this when a channel is killed or completed.

Source

pub async fn inject( &self, channel_id: ChannelId, event: Event, ) -> Result<(), EngineError>

Injects a direct event into a specific channel (subscription filter bypassed).

This enables targeted event injection (e.g., @component routing) at any time. The receiving ChannelRunner will process the event regardless of its subscription list.

§Arguments

channel_id - Target channel
event - Event to inject

§Errors

Returns EngineError::ChannelNotFound if the channel is not registered. Returns EngineError::SendFailed if the channel’s buffer is full or closed.

Source

pub fn try_inject( &self, channel_id: ChannelId, event: Event, ) -> Result<(), EngineError>

Try to inject a direct event without blocking (subscription filter bypassed).

Returns immediately if the buffer is full.

§Errors

Returns error if channel not found, buffer full, or channel closed.

Source

pub fn broadcast(&self, event: Event) -> usize

Broadcasts an event to all registered channels (subscription filter applies).

This is used for data-plane events (e.g., UserInput) that need to reach all channels. Unlike Signal broadcast (control-plane, high priority), this operates on the data-plane via channel event queues.

Each receiving ChannelRunner will apply its subscription filter — only channels subscribed to the event’s category will process it.