message_bus
Generated Rust API reference for byte_engine.
byte_engine / core / message_bus
Module message_bus
Chunked storage shared by the engine's typed message routes.
Create one MessageBus during application startup, call
MessageBus::begin_tick once per tick, then create a MessageScope
for each independently owned group of channels. Message types are
registered lazily the first time a channel requests them. Every route
borrows fixed-size chunks from the bus's one pool as it publishes and
returns them once every listener has read them, so no route needs its own
capacity and a burst on one type only takes chunks that are free.
Publication and reading are lock-free. A publisher reserves a slot with one
compare-and-swap on the route's current chunk and commits it with one
release store. A listener reads with one acquire load per message. The bus
takes its control lock only to attach a chunk to a route, to register a
route or a listener, and inside MessageBus::begin_tick.
When the pool has no free chunk, a publisher waits instead of overwriting
or dropping a message. The bus's first wait logs a warning that suggests a
larger messages.capacity. After one second of waiting, a publisher logs
which routes hold the pool and where their slowest listener was created. A
system that stops reading its messages must drop its listener so the chunks
behind it return to the pool.
Contents
Quick Reference
| Item | Kind | Description |
|---|---|---|
MessageBusConfig | struct | The MessageBusConfig struct defines the storage and tick behavior a bus is created with. |
ListenerSnapshot | struct | The ListenerSnapshot struct reports how far one typed listener lags its route. |
TopicSnapshot | struct | The TopicSnapshot struct reports one typed route's current state for diagnostics. |
PoolSnapshot | struct | The PoolSnapshot struct reports the shared chunk pool's state for diagnostics. |
MessageBus | struct | The MessageBus struct owns one shared chunk pool and the lazy route registry over it. |
MessageScope | struct | The MessageScope struct isolates typed routes owned by one subsystem while sharing bus storage. |
MessageBusConfigError | enum | The MessageBusConfigError enum explains why startup storage cannot be allocated. |
MessageRouteError | enum | The MessageRouteError enum explains why a lazy typed route cannot be acquired. |
CHUNK_BYTES | const | Bytes in one pool chunk. |
Structs
MessageBusConfig
struct MessageBusConfig {
pub capacity: usize,
pub ticks: bool,
}Defined in crates/byte-engine/src/core/message_bus.rs:86-96
The MessageBusConfig struct defines the storage and tick behavior a bus is created with.
Fields
-
capacity:usizeBytes of chunk storage shared by every route. Rounded down to whole chunks of
CHUNK_BYTES. -
ticks:boolWhether the owner calls
MessageBus::begin_tickonce per tick.On a ticking bus a listener replays the current tick's earlier messages and chunks stay until their tick ends. A bus without ticks keeps listeners future-only and recycles chunks as soon as every listener has read them, which suits standalone channels and tests.
Implementations
-
fn new(capacity: usize) -> SelfCreates a ticking configuration with the supplied pool size in bytes.
Next, pass the result to
MessageBus::new.
Trait Implementations
impl ArchivePointee for MessageBusConfig
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for MessageBusConfig
impl Clone for MessageBusConfig
-
fn clone(&self) -> MessageBusConfigRelated:
MessageBusConfig
impl Copy for MessageBusConfig
impl Debug for MessageBusConfig
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Default for MessageBusConfig
-
fn default() -> Self
impl Downcast for MessageBusConfig
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for MessageBusConfig
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Eq for MessageBusConfig
impl<K> Equivalent for MessageBusConfig
-
fn equivalent(&self, key: &K) -> bool
impl Instrument for MessageBusConfig
impl LayoutRaw for MessageBusConfig
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for MessageBusConfig
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for MessageBusConfig
-
fn eq(&self, other: &MessageBusConfig) -> boolRelated:
MessageBusConfig
impl Pointee for MessageBusConfig
-
type Metadata = ()
impl Read for MessageBusConfig
impl<R> ReadPrimitive for MessageBusConfig
impl StructuralPartialEq for MessageBusConfig
impl WithSubscriber for MessageBusConfig
ListenerSnapshot
struct ListenerSnapshot {
pub behind: u64,
pub created_at: &'static std::panic::Location<'static>,
}Defined in crates/byte-engine/src/core/message_bus.rs:200-205
The ListenerSnapshot struct reports how far one typed listener lags its route.
Fields
-
behind:u64Messages published on the route that this listener has not read yet.
-
created_at:&'static std::panic::Location<'static>Source location of the call that created the listener.
Trait Implementations
impl ArchivePointee for ListenerSnapshot
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for ListenerSnapshot
impl Clone for ListenerSnapshot
-
fn clone(&self) -> ListenerSnapshotRelated:
ListenerSnapshot
impl Copy for ListenerSnapshot
impl Debug for ListenerSnapshot
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for ListenerSnapshot
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for ListenerSnapshot
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Eq for ListenerSnapshot
impl<K> Equivalent for ListenerSnapshot
-
fn equivalent(&self, key: &K) -> bool
impl Instrument for ListenerSnapshot
impl LayoutRaw for ListenerSnapshot
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for ListenerSnapshot
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for ListenerSnapshot
-
fn eq(&self, other: &ListenerSnapshot) -> boolRelated:
ListenerSnapshot
impl Pointee for ListenerSnapshot
-
type Metadata = ()
impl Read for ListenerSnapshot
impl StructuralPartialEq for ListenerSnapshot
impl WithSubscriber for ListenerSnapshot
TopicSnapshot
struct TopicSnapshot {
pub topic_id: usize,
pub scope_id: u64,
pub scope: std::sync::Arc<str>,
pub message_type: &'static str,
pub active_listeners: usize,
pub published: u64,
pub chunks: usize,
pub slowest_listener: Option<ListenerSnapshot>,
}Defined in crates/byte-engine/src/core/message_bus.rs:209-221
The TopicSnapshot struct reports one typed route's current state for diagnostics.
Fields
-
published:u64Messages published on this route since the bus was created.
-
chunks:usizePool chunks this route currently holds.
-
slowest_listener:Option<ListenerSnapshot>The listener furthest behind the route's latest message, if any listener exists.
Trait Implementations
impl ArchivePointee for TopicSnapshot
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for TopicSnapshot
impl Clone for TopicSnapshot
-
fn clone(&self) -> TopicSnapshotRelated:
TopicSnapshot
impl Debug for TopicSnapshot
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for TopicSnapshot
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for TopicSnapshot
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Eq for TopicSnapshot
impl<K> Equivalent for TopicSnapshot
-
fn equivalent(&self, key: &K) -> bool
impl Instrument for TopicSnapshot
impl LayoutRaw for TopicSnapshot
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for TopicSnapshot
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for TopicSnapshot
-
fn eq(&self, other: &TopicSnapshot) -> boolRelated:
TopicSnapshot
impl Pointee for TopicSnapshot
-
type Metadata = ()
impl Read for TopicSnapshot
impl StructuralPartialEq for TopicSnapshot
impl WithSubscriber for TopicSnapshot
PoolSnapshot
struct PoolSnapshot {
pub chunks: usize,
pub waits: u64,
}Defined in crates/byte-engine/src/core/message_bus.rs:225-229
The PoolSnapshot struct reports the shared chunk pool's state for diagnostics.
Fields
-
waits:u64Times a publisher had to wait for a chunk because the pool was exhausted.
Trait Implementations
impl ArchivePointee for PoolSnapshot
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for PoolSnapshot
impl Clone for PoolSnapshot
-
fn clone(&self) -> PoolSnapshotRelated:
PoolSnapshot
impl Copy for PoolSnapshot
impl Debug for PoolSnapshot
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for PoolSnapshot
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for PoolSnapshot
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Eq for PoolSnapshot
impl<K> Equivalent for PoolSnapshot
-
fn equivalent(&self, key: &K) -> bool
impl Instrument for PoolSnapshot
impl LayoutRaw for PoolSnapshot
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for PoolSnapshot
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for PoolSnapshot
-
fn eq(&self, other: &PoolSnapshot) -> boolRelated:
PoolSnapshot
impl Pointee for PoolSnapshot
-
type Metadata = ()
impl Read for PoolSnapshot
impl StructuralPartialEq for PoolSnapshot
impl WithSubscriber for PoolSnapshot
MessageBus
struct MessageBus {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/core/message_bus.rs:233-235
The MessageBus struct owns one shared chunk pool and the lazy route registry over it.
Implementations
-
fn new(config: MessageBusConfig) -> Result<Self, MessageBusConfigError>Related:
MessageBusConfig,MessageBusConfigErrorAllocates the chunk pool and an empty route registry.
Next, call
Self::new_scopefor each owner that needs isolated typedroutes. On a ticking configuration, call
Self::begin_tickonce pertick so listeners created during a tick replay its earlier messages.
-
fn observe(&self) -> Result<MessageObserver, MessageObservationError>Related:
MessageObserver,MessageObservationErrorAttaches the one passive observer for this bus.
The observer sees successful publications from every future route,
including application-defined generic types. Attach it before acquiring
the first channel or factory. Publication observation reads existing route
counters, so it never delays publishers.
-
fn begin_tick(&self)Starts a tick: listeners created from now on replay this tick's messages.
Call this once per application tick before any system publishes. It also
destroys the previous tick's payloads that every listener has read and
returns the chunks nobody still reads to the pool.
-
fn new_scope(&self, name: impl Into<Arc<str>>) -> MessageScopeRelated:
MessageScopeCreates an isolated namespace over the same chunk pool.
Routes remain lazy: creating a scope does not register a route until code
requests a concrete message type from it.
-
fn topics(&self) -> Vec<TopicSnapshot>Related:
TopicSnapshotReturns a diagnostic snapshot of every route registered so far, in route id order.
-
fn pool(&self) -> PoolSnapshotRelated:
PoolSnapshotReturns the shared pool's current occupancy.
Trait Implementations
impl ArchivePointee for MessageBus
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for MessageBus
impl Clone for MessageBus
-
fn clone(&self) -> MessageBusRelated:
MessageBus
impl Default for MessageBus
-
fn default() -> Self
impl Downcast for MessageBus
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for MessageBus
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for MessageBus
impl LayoutRaw for MessageBus
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for MessageBus
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for MessageBus
-
type Metadata = ()
impl Read for MessageBus
impl<R> ReadPrimitive for MessageBus
impl WithSubscriber for MessageBus
MessageScope
struct MessageScope {
// [REDACTED: Private Fields]
}Defined in crates/byte-engine/src/core/message_bus.rs:357-361
The MessageScope struct isolates typed routes owned by one subsystem while sharing bus storage.
Implementations
-
fn channel<M>(&self) -> DefaultChannel<M>Acquires the canonical typed channel in this scope, registering it on first use.
Next, create listeners before publishing messages that they must observe.
-
fn try_channel<M>(&self) -> Result<DefaultChannel<M>, MessageRouteError>Related:
MessageRouteErrorTries to acquire the canonical typed channel in this scope.
-
fn factory<T>(&self) -> Factory<T>Acquires the canonical creation factory for
Tin this scope.The factory registers
CreateMessage<T>only when this method is firstcalled, so application-defined types require no startup declaration.
-
fn name(&self) -> &strReturns this scope's diagnostic name.
-
fn standalone(name: impl Into<Arc<str>>) -> SelfCreates a scope on a private bus without ticks, so its listeners are future-only.
Use it where no application owns a bus, such as servers and tests. Applications use
MessageBus::new_scopeso the scope's routes appear in their unified diagnostics.
Trait Implementations
impl ArchivePointee for MessageScope
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for MessageScope
impl Clone for MessageScope
-
fn clone(&self) -> MessageScopeRelated:
MessageScope
impl Debug for MessageScope
-
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for MessageScope
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for MessageScope
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for MessageScope
impl LayoutRaw for MessageScope
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for MessageScope
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for MessageScope
-
type Metadata = ()
impl Read for MessageScope
impl WithSubscriber for MessageScope
Enums
MessageBusConfigError
enum MessageBusConfigError {
CapacityTooSmall {
capacity: usize,
minimum: usize,
},
}Defined in crates/byte-engine/src/core/message_bus.rs:133-136
The MessageBusConfigError enum explains why startup storage cannot be allocated.
Variants
-
CapacityTooSmallThe pool cannot hold the two chunks one route needs to seal a full chunk.
Trait Implementations
impl ArchivePointee for MessageBusConfigError
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for MessageBusConfigError
impl Clone for MessageBusConfigError
-
fn clone(&self) -> MessageBusConfigErrorRelated:
MessageBusConfigError
impl Debug for MessageBusConfigError
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Display for MessageBusConfigError
-
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for MessageBusConfigError
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for MessageBusConfigError
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Eq for MessageBusConfigError
impl<K> Equivalent for MessageBusConfigError
-
fn equivalent(&self, key: &K) -> bool
impl Error for MessageBusConfigError
impl Instrument for MessageBusConfigError
impl LayoutRaw for MessageBusConfigError
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for MessageBusConfigError
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for MessageBusConfigError
-
fn eq(&self, other: &MessageBusConfigError) -> boolRelated:
MessageBusConfigError
impl Pointee for MessageBusConfigError
-
type Metadata = ()
impl Read for MessageBusConfigError
impl StructuralPartialEq for MessageBusConfigError
impl ToString for MessageBusConfigError
-
fn to_string(&self) -> String
impl WithSubscriber for MessageBusConfigError
MessageRouteError
enum MessageRouteError {
MessageTooLarge {
message_type: &'static str,
message_bytes: usize,
chunk_bytes: usize,
},
MessageOveraligned {
message_type: &'static str,
required_alignment: usize,
chunk_alignment: usize,
},
}Defined in crates/byte-engine/src/core/message_bus.rs:156-169
The MessageRouteError enum explains why a lazy typed route cannot be acquired.
Variants
-
MessageTooLargeOne message and its slot header cannot fit in a chunk.
-
MessageOveralignedThe message requires stricter alignment than a chunk provides.
Trait Implementations
impl ArchivePointee for MessageRouteError
-
type ArchivedMetadata = () -
fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for MessageRouteError
impl Clone for MessageRouteError
-
fn clone(&self) -> MessageRouteErrorRelated:
MessageRouteError
impl Debug for MessageRouteError
-
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Display for MessageRouteError
-
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for MessageRouteError
-
fn into_any(self: Box<T>) -> Box<dyn Any> -
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any> -
fn as_any(&self) -> &dyn Any -
fn as_any_mut(&mut self) -> &mut dyn Any
impl DowncastSync for MessageRouteError
-
fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Eq for MessageRouteError
impl<K> Equivalent for MessageRouteError
-
fn equivalent(&self, key: &K) -> bool
impl Error for MessageRouteError
impl Instrument for MessageRouteError
impl LayoutRaw for MessageRouteError
-
fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for MessageRouteError
-
unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool -
fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for MessageRouteError
-
fn eq(&self, other: &MessageRouteError) -> boolRelated:
MessageRouteError
impl Pointee for MessageRouteError
-
type Metadata = ()
impl Read for MessageRouteError
impl StructuralPartialEq for MessageRouteError
impl ToString for MessageRouteError
-
fn to_string(&self) -> String
impl WithSubscriber for MessageRouteError
Constants
CHUNK_BYTES
const CHUNK_BYTES: usize = 65_536usize;Defined in crates/byte-engine/src/core/message_bus.rs:56
Bytes in one pool chunk. A chunk holds whole slots of one message type, so one message must fit in a chunk together with its slot header.