Struct LiveNode 

pub struct LiveNode { /* private fields */ }

High-level abstraction for a live Nautilus system node.

Provides a simplified interface for running live systems with automatic client management and lifecycle handling.

Implementations

impl LiveNode

pub fn builder( trader_id: TraderId, environment: Environment, ) -> Result<LiveNodeBuilder>

Creates a new LiveNodeBuilder for fluent configuration.

Errors

Returns an error if the environment is invalid for live trading.

pub fn build(name: String, config: Option<LiveNodeConfig>) -> Result<Self>

Creates a new LiveNode directly from a kernel name and optional configuration.

This is a convenience method for creating a live node with a pre-configured kernel configuration, bypassing the builder pattern. If no config is provided, a default configuration will be used.

Errors

Returns an error if kernel construction fails.

pub fn add_plugin(&mut self, config: PluginConfig) -> Result<()>

Loads and registers one plug-in instance.

Errors

Returns an error because dynamic plug-in hosting lives in the host-side integration.

pub fn handle(&self) -> LiveNodeHandle

Returns a thread-safe handle to control this node.

pub async fn start(&mut self) -> Result<()>

Starts the live node without entering a select loop.

Connects clients, runs reconciliation, and starts the trader, but does not consume the runner or drive channel receivers, so channel traffic arriving after startup is never serviced. This is a building block for tests and embedding, not a lifecycle: use run or run_with_mode to run a node.

Errors

Returns an error if startup fails.

pub async fn stop(&mut self) -> Result<()>

Stop the live node.

This method stops the trader, waits for the configured grace period to allow residual events to be processed, then finalizes the shutdown sequence.

Errors

Returns an error if shutdown fails.

pub fn dispose(&mut self)

Disposes the live node kernel and releases resources.

pub async fn run(&mut self) -> Result<()>

Run the live node with automatic shutdown handling.

This method starts the node, runs indefinitely, and handles graceful shutdown on interrupt signals.

Thread Safety

The event loop runs directly on the current thread (not spawned) because the msgbus uses thread-local storage. Endpoints registered by the kernel are only accessible from the same thread.

Shutdown Sequence

1. Signal received (SIGINT, SIGTERM, or handle stop).
2. Trader components stopped (triggers order cancellations, etc.).
3. Event loop continues processing residual events for the configured grace period.
4. Kernel finalized, clients disconnected, remaining events drained.

Errors

Returns an error if the node fails to start or encounters a runtime error.

pub async fn run_with_mode(&mut self, mode: NodeRunMode) -> Result<()>

Run the live node under the given mode.

NodeRunMode::Hosted leaves signal handling to the host application. Every other responsibility, including maintenance, reconciliation, external ingress, and the shutdown sequence, is identical across modes so that hosted and owned nodes cannot diverge.

Errors

Returns an error if the node fails to start or encounters a runtime error.

pub const fn has_pending_cache_database(&self) -> bool

Returns whether a cache database backing is configured but not yet installed.

pub fn environment(&self) -> Environment

Gets the node’s environment.

pub const fn kernel(&self) -> &NautilusKernel

Gets a reference to the underlying kernel.

pub const fn kernel_mut(&mut self) -> &mut NautilusKernel

Gets an exclusive reference to the underlying kernel.

pub fn trader_id(&self) -> TraderId

Gets the node’s trader ID.

pub const fn instance_id(&self) -> UUID4

Gets the node’s instance ID.

pub fn state(&self) -> NodeState

Returns the current node state.

pub fn is_running(&self) -> bool

Checks if the live node is currently running.

pub fn set_cache_database( &mut self, database: Box<dyn CacheDatabaseAdapter>, ) -> Result<()>

Sets the cache database adapter for persistence.

This allows setting a database adapter (e.g., PostgreSQL, Redis) after the node is built but before it starts running. The database adapter is used to persist cache data for recovery and state management.

Errors

Returns an error if the node is already running.

pub fn exec_manager(&self) -> &ExecutionManager

Returns the execution manager.

pub fn exec_manager_mut(&mut self) -> &mut ExecutionManager

Returns a mutable reference to the execution manager.

pub fn add_actor<T>(&mut self, actor: T) -> Result<()>

where T: DataActor + DataActorNative + Component + Actor + 'static,

Adds an actor to the trader.

This method provides a high-level interface for adding actors to the underlying trader without requiring direct access to the kernel. Actors should be added after the node is built but before starting the node.

Errors

Returns an error if:

• The trader is not in a valid state for adding components.
• An actor with the same ID is already registered.
• The node is currently running.

pub fn add_actor_from_factory<F, T>(&mut self, factory: F) -> Result<()>

where F: FnOnce() -> Result<T>, T: DataActor + DataActorNative + Component + Actor + 'static,

Adds an actor to the live node using a factory function.

The factory function is called at registration time to create the actor, avoiding cloning issues with non-cloneable actor types.

Errors

Returns an error if:

• The node is currently running.
• The factory function fails to create the actor.
• The underlying trader registration fails.

pub fn add_strategy<T>(&mut self, strategy: T) -> Result<()>

where T: Strategy + StrategyNative + DataActorNative + Component + Debug + 'static,

Adds a strategy to the trader.

Strategies are registered in both the component registry (for lifecycle management) and the actor registry (for data callbacks via msgbus).

Errors

Returns an error if:

• The node is currently running.
• A strategy with the same ID is already registered.
• The strategy configures one or more external order claims and the request repeats an instrument, or either tier already contains a requested claim.
• The strategy configures one or more external order claims or an OMS type override, and the execution engine is already borrowed. A strategy configuring neither does not take the borrow and cannot fail this way.

pub fn register_external_order_claims( &mut self, strategy_id: StrategyId, claims: &[InstrumentId], ) -> Result<()>

Registers external order claims on both live execution tiers.

The operation is synchronous and atomic across the reconciliation manager and execution engine. It can be called while the node is idle, after manual start returns, or after the node stops. It cannot be called while run or run_with_mode owns the node.

Errors

Returns an error without changing either tier if the execution engine is already borrowed, the request repeats an instrument, or either tier already contains any requested claim.

pub fn deregister_external_order_claims( &mut self, strategy_id: StrategyId, ) -> Result<()>

Deregisters all external order claims owned by strategy_id from both execution tiers.

Remove the strategy through the trader or controller first, then call this method before registering a successor. The operation is synchronous and can be called while the node is idle, after manual start returns, or after the node stops. It cannot be called while run or run_with_mode owns the node.

Errors

Returns an error without changing either tier if the execution engine is already borrowed or the two tiers do not contain identical claim sets for the strategy.

pub fn add_exec_algorithm<T>(&mut self, exec_algorithm: T) -> Result<()>

where T: ExecutionAlgorithm + ExecutionAlgorithmNative + Component + Debug + 'static,

Adds an execution algorithm to the trader.

Execution algorithms are registered in both the component registry (for lifecycle management) and the actor registry (for data callbacks via msgbus).

Errors

Returns an error if:

• The node is currently running.
• An execution algorithm with the same ID is already registered.

Trait Implementations

impl Debug for LiveNode

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

Formats the value using the given formatter.