Rust edition: this page follows the live DeepWiki structure but treats the current Rust crates as implementation authority. Non-Rust surfaces are identified at their boundary and are not presented as Rust APIs.

Component Lifecycle and State Machine

Relevant Rust source files

• crates/common/src/component.rs
• crates/common/src/messages/system/component.rs
• crates/risk/src/engine/mod.rs
• crates/system/src/trader.rs

Overview

NautilusTrader implements a rigorous component lifecycle management system where all components (strategies, actors, engines, clients) follow a standardized state machine. The system uses a hybrid architecture:

• Rust FSM Core: The state definitions and trigger logic are defined in Rust and exported via C headers for consistency across the hybrid boundary
• Rust component contract: The Component trait and registry expose lifecycle hooks and state transitions to engines and actors.
• State Validation: All state transitions are validated to prevent invalid operations, such as attempting to start a component that is already in a terminal state

Key aspects covered:

• ComponentState and ComponentTrigger enumerations.
• The Component base class and its state management.
• Two-layer lifecycle method pattern (public API + protected hooks).
• Registration and initialization pattern within the NautilusKernel.
• Component hierarchy and lifecycle coordination in TradingNode.

Sources:

ComponentState and ComponentTrigger

ComponentState Enumeration

The Rust ComponentState enum defines the current lifecycle status of a component.

State	Description
PRE_INITIALIZED	When a component is instantiated, but not yet ready to fulfill its specification
READY	When a component is able to be started
STARTING	When a component is executing its actions on start
RUNNING	When a component is operating normally and can fulfill its specification
STOPPING	When a component is executing its actions on stop
STOPPED	When a component has successfully stopped
RESUMING	When a component is started again after its initial start
RESETTING	When a component is executing its actions on reset
DISPOSING	When a component is executing its actions on dispose
DISPOSED	When a component has successfully shut down and released all resources
FAULTED	When a component has successfully shut down due to a detected fault

ComponentTrigger Enumeration

The ComponentTrigger enum defines the events that cause state transitions. These triggers drive the internal logic of the component state machine

Trigger	Initiates Transition
INITIALIZE	A trigger for the component to initialize
START	A trigger for the component to start
START_COMPLETED	A trigger when the component has successfully started
STOP	A trigger for the component to stop
STOP_COMPLETED	A trigger when the component has successfully stopped
DISPOSE	A trigger for the component to dispose and release resources

Sources:

State Transition Diagram

Diagram — Component state machine with valid transitions

Trigger family	Transitional state	Stable result
INITIALIZE	initialization	READY
START / START_COMPLETED	STARTING	RUNNING
STOP / STOP_COMPLETED	STOPPING	STOPPED
RESUME / RESUME_COMPLETED	RESUMING	RUNNING
RESET / RESET_COMPLETED	RESETTING	READY
DISPOSE / DISPOSE_COMPLETED	DISPOSING	DISPOSED
DEGRADE / DEGRADE_COMPLETED	DEGRADING	DEGRADED
FAULT / FAULT_COMPLETED	FAULTING	FAULTED

The ComponentState and ComponentTrigger enums defined in common.h provide the formal structure for this diagram

Sources:

Component Base Class Architecture

Component Class Implementation

The Rust Component trait defines the lifecycle contract, while concrete components own or receive the clock, logging identity, and message-bus handlers they require.

Diagram — Rust component structure and code entities

Component State Properties

The Component class uses the ComponentState enum to manage its internal status, accessible via the _fsm (Finite State Machine) instance

Sources:

Two-Layer Lifecycle Method Pattern

Components implement lifecycle behavior using a two-layer pattern that separates state management from implementation logic.

Layer 1: Public API Methods

Public methods handle state validation and transition triggers. For example, the NautilusKernel manages the startup of its constituent engines by calling their lifecycle methods during the start sequence

Layer 2: Protected Implementation Methods

Concrete Rust components implement lifecycle behavior and register message-bus handlers during initialization. RiskEngine, for example, also constructs throttlers used for order submission and modification.

Component Type	Lifecycle Coordination
NautilusKernel	Coordinates DataEngine, ExecutionEngine, Portfolio, and RiskEngine
TradingNode	Orchestrates the NautilusKernel and high-level build/run phases
RiskEngine	Manages pre-trade risk checks and throttles trading commands

Sources:

Component Registration and Initialization

Registration Pattern

Components are typically constructed in a PRE_INITIALIZED state. They become functional after registration with the NautilusKernel, which injects core system dependencies such as the MessageBus, Cache, and Clock

Diagram — Component initialization and kernel orchestration

Sources:

Engine Lifecycle Coordination

LiveNode

The Rust LiveNode orchestrates startup and shutdown through NautilusKernel.

• Build Phase: Uses LiveNodeBuilder to construct clients and register them with engines
• Run Phase: The is_running() method checks the underlying kernel state
• Shutdown: Handles signals and graceful termination

NautilusKernel

The NautilusKernel serves as the central orchestration point, managing the Clock, Logger, and MessageBus for all attached engines It supports different environments (BACKTEST, SANDBOX, LIVE) and selects the appropriate clock type accordingly

RiskEngine

The Rust RiskEngine follows the component lifecycle while managing the ACTIVE, REDUCING, and HALTED trading states. Its throttlers bound message rates and protect downstream components.

Sources:

Summary

The component lifecycle system provides:

1. Standardized State Management: Defined in Rust and shared via FFI for consistency
2. Validated Transitions: Enforced through the ComponentTrigger logic
3. Coordinated Orchestration: Managed by the NautilusKernel to ensure dependencies are injected before startup
4. Environment Awareness: The system automatically switches between TestClock and LiveClock based on the configuration

Sources: