Skip to main content

Module core

nautilus_common::msgbus

Module core 

Source
Expand description

Core message bus implementation.

§Design decisions

§Why two routing mechanisms?

The message bus provides typed and Any-based routing to balance performance and flexibility:

Typed routing optimizes for throughput on known data types:

  • TopicRouter<T> for pub/sub, EndpointMap<T> for point-to-point.
  • Handlers implement Handler<T>, receive &T directly.
  • No runtime type checking enables inlining and static dispatch.
  • Built-in routers: QuoteTick, TradeTick, Bar, OrderBookDeltas, OrderBookDepth10, OrderEventAny, PositionEvent, AccountState.

Any-based routing provides flexibility for extensibility:

  • subscriptions/topics maps with ShareableMessageHandler.
  • Handlers implement Handler<dyn Any>, receive &dyn Any.
  • Supports arbitrary message types without modifying the bus.
  • Required for Python interop where types aren’t known at compile time.

§Handler semantics

Typed handlers receive &T references:

  • Same message delivered to N handlers without cloning.
  • Handler decides whether to clone (only if storing).
  • Zero-cost for Copy types (QuoteTick, TradeTick, Bar).
  • Efficient for large types (OrderBookDeltas).

Any-based handlers pay per-handler overhead:

  • Each handler receives &dyn Any, must downcast to &T.
  • N handlers = N downcasts + N potential clones.
  • Runtime type checking on every dispatch.

§Performance trade-off

Typed routing is faster (see benches/msgbus_typed.rs, AMD Ryzen 9 7950X):

ScenarioTyped vs Any
Handler dispatch (noop)~10x faster
Router with 5 subscribers~3.5x faster
Router with 10 subscribers~2x faster
High volume (1M messages)~7% faster

Any-based routing pays for flexibility with runtime type checking. Use typed routing for hot-path data; Any-based for custom types and Python.

§Routing paths are separate

Typed and Any-based routing use separate data structures:

  • publish_quote routes through router_quotes.
  • publish_any routes through topics.

Publishers and subscribers must use matching APIs. Mixing them causes silent message loss.

§When to use each

Typed (publish_quote, subscribe_quotes, etc.):

  • Market data (quotes, trades, bars, order book updates).
  • Order and position events.
  • High-frequency data with known types.

Any-based (publish_any, subscribe_any):

  • Custom or user-defined data types.
  • Low-frequency messages.
  • Python callbacks.

Structs§

MessageBus
A generic message bus to facilitate various messaging patterns.
Subscription
Represents a subscription to a particular topic.