Struct Trader 

pub struct Trader {
    pub trader_id: TraderId,
    pub instance_id: UUID4,
    pub environment: Environment,
    /* private fields */
}

Central orchestrator for managing trading components.

The Trader manages the lifecycle and coordination of actors, strategies, and execution algorithms within the trading system. It provides component registration, state management, and integration with system engines.

Notes

Strategies implement Strategy::stop() -> bool which returns whether to proceed with the component stop. This enables manage_stop behavior where the strategy can defer stopping until a market exit completes.

We store type-erased closures because the component registry stores trait objects and we need to call Strategy::stop() which requires the concrete type. The closure is created during add_strategy when the concrete type T is known.

Fields

trader_id: TraderId

The unique trader identifier.

instance_id: UUID4

The unique instance identifier.

environment: Environment

The trading environment context.

Implementations

impl Trader

pub fn new( trader_id: TraderId, instance_id: UUID4, environment: Environment, clock_factory: ClockFactory, cache: Rc<RefCell<Cache>>, portfolio: Rc<RefCell<Portfolio>>, ) -> Self

Creates a new Trader instance.

pub const fn trader_id(&self) -> TraderId

Returns the trader ID.

pub const fn instance_id(&self) -> UUID4

Returns the instance ID.

pub const fn environment(&self) -> Environment

Returns the trading environment.

pub const fn state(&self) -> ComponentState

Returns the current component state.

pub const fn ts_created(&self) -> UnixNanos

Returns the timestamp when the trader was created (UNIX nanoseconds).

pub const fn ts_started(&self) -> Option<UnixNanos>

Returns the timestamp when the trader was last started (UNIX nanoseconds).

pub const fn ts_stopped(&self) -> Option<UnixNanos>

Returns the timestamp when the trader was last stopped (UNIX nanoseconds).

pub const fn actor_count(&self) -> usize

Returns the number of registered actors.

pub const fn strategy_count(&self) -> usize

Returns the number of registered strategies.

pub const fn exec_algorithm_count(&self) -> usize

Returns the number of registered execution algorithms.

pub fn get_component_clocks(&self) -> Vec<Rc<RefCell<dyn Clock>>>

Returns references to all component clocks for backtest time advancement.

pub const fn component_count(&self) -> usize

Returns the total number of registered components.

pub fn actor_ids(&self) -> Vec<ActorId>

Returns a list of all registered actor IDs.

pub fn strategy_ids(&self) -> Vec<StrategyId>

Returns a list of all registered strategy IDs.

pub fn exec_algorithm_ids(&self) -> Vec<ExecAlgorithmId>

Returns a list of all registered execution algorithm IDs.

pub fn create_component_clock( &mut self, component_id: ComponentId, ) -> Rc<RefCell<dyn Clock>>

Creates a clock for a component and registers it for time advancement.

Each component gets its own clock instance so that the default time event callback registered on each clock is independent. In backtest mode, the clocks are also used for deterministic time advancement by the engine.

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

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

Adds an actor to the trader.

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.

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

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

Adds an actor to the trader 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 factory function fails to create the actor.
• The trader is not in a valid state for adding components.
• An actor with the same ID is already registered.

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

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

Adds an already registered actor to the trader’s component registry.

Errors

Returns an error if the actor cannot be registered in the component registry.

pub fn add_actor_id_for_lifecycle<T>(&mut self, actor_id: ActorId) -> Result<()>

where T: DataActor + DataActorNative + Debug + 'static,

Adds an actor ID to the trader’s lifecycle management without consuming the actor.

This is useful when the actor is already registered in the global component registry but the trader needs to track it for lifecycle management. The caller is responsible for ensuring the actor is properly registered in the global registries.

Errors

Returns an error if the actor ID is already tracked by this trader.

pub fn add_exec_algorithm_id_for_lifecycle( &mut self, exec_algorithm_id: ExecAlgorithmId, ) -> Result<()>

Adds an externally-registered execution algorithm ID to the trader for lifecycle management.

The execution algorithm must already be registered in the global component and actor registries. This method only tracks the ID so the trader can manage the algorithm’s lifecycle (start/stop/dispose).

Errors

Returns an error if an execution algorithm with the same ID is already tracked.

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

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

Adds an externally-registered strategy to the trader for lifecycle management and installs its order/position event subscriptions, stop hook, and control endpoint.

The strategy must already be registered in the global component and actor registries. The generic parameter T must match the concrete type stored in those registries so that the typed event handlers can retrieve it.

Errors

Returns an error if the strategy ID is already tracked by this trader.

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

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

Prepares a strategy ID and order ID tag before registration.

Errors

Returns an error if the configured order ID tag contains the ‘-’ strategy ID separator, if composing it into a strategy ID does not produce a valid [StrategyId], or if the strategy ID or order ID tag is already registered.

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). The strategy’s StrategyCore is also registered with the portfolio for order management.

Errors

Returns an error if:

• The trader is not in a valid state for adding components.
• A strategy with the same ID is already registered.

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 trader is not in a valid state for adding components.
• An execution algorithm with the same ID is already registered.

pub fn start_components(&mut self) -> Result<()>

Starts all registered components.

Errors

Returns an error if any component fails to start.

pub fn start_with_component_callbacks(trader: &Rc<RefCell<Self>>) -> Result<()>

Starts the trader while releasing the trader borrow before component callbacks run.

Errors

Returns an error if the trader state transition or any component startup fails.

pub fn stop_components(&mut self) -> Result<()>

Stops all registered components.

Errors

Returns an error if any component fails to stop.

pub fn stop_after_start_failure(&mut self) -> Result<()>

Stops a partially started trader without deferring managed strategy shutdown.

Errors

Returns an error if the trader transition or any component stop fails. All registered components still receive a stop attempt before the error is returned.

pub fn reset_components(&mut self) -> Result<()>

Resets all registered components.

Errors

Returns an error if any component fails to reset.

pub fn dispose_components(&mut self) -> Result<()>

Disposes of all registered components.

Errors

Returns an error if any component fails to dispose.

pub fn clear_strategies(&mut self) -> Result<()>

Clears all registered strategies, disposing each and removing their clocks.

Errors

Returns an error if any strategy fails to dispose.

pub fn clear_actors(&mut self) -> Result<()>

Clears all registered actors, disposing each and removing their clocks.

Errors

Returns an error if any actor fails to dispose.

pub fn clear_exec_algorithms(&mut self) -> Result<()>

Clears all registered execution algorithms, disposing each and removing their clocks.

Errors

Returns an error if any execution algorithm fails to dispose.

pub fn start_actor(&self, actor_id: &ActorId) -> Result<()>

Starts the actor with the given actor_id.

Errors

Returns an error if the actor is not registered or cannot be started.

pub fn stop_actor(&self, actor_id: &ActorId) -> Result<()>

Stops the actor with the given actor_id.

Errors

Returns an error if the actor is not registered or cannot be stopped.

pub fn remove_actor(&mut self, actor_id: &ActorId) -> Result<()>

Removes the actor with the given actor_id.

Will stop the actor first if it is currently running. Disposes the actor and removes it from the trader’s tracking.

Errors

Returns an error if the actor is not registered, or if disposal fails. A failed disposal keeps the actor registered and tracked, and leaves it Faulted; see [Component::dispose]. Calling this again retires the actor.

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

Starts the strategy with the given strategy_id.

Errors

Returns an error if the strategy is not registered or cannot be started.

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

Stops the strategy with the given strategy_id.

Respects the manage_stop behavior - if the strategy’s stop function returns false, the component stop is deferred until market exit completes.

Errors

Returns an error if the strategy is not registered or cannot be stopped.

pub fn market_exit_strategy( trader: &Rc<RefCell<Self>>, strategy_id: &StrategyId, ) -> Result<()>

Exits the market for the strategy with the given strategy_id.

Sends a strategy command to the strategy’s control endpoint. The strategy then performs its own managed market exit.

Errors

Returns an error if the strategy is not registered or its control endpoint is missing.

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

Removes the strategy with the given strategy_id.

Will stop the strategy first if it is currently running. Disposes the strategy and removes it from the trader’s tracking along with its event subscriptions.

Errors

Returns an error if the strategy is not registered, or if disposal fails. A failed disposal keeps the strategy registered and tracked, and leaves it Faulted; see [Component::dispose]. Calling this again retires the strategy.

pub fn initialize(&mut self) -> Result<()>

Initializes the trader, transitioning from PreInitialized to Ready state.

This method must be called before starting the trader.

Errors

Returns an error if the trader cannot be initialized from its current state.

impl Trader

pub fn add_actor_from_importable_config( &mut self, config: &ImportableActorConfig, ) -> Result<ActorId>

Adds an importable Python actor to the trader.

Errors

Returns an error if the actor cannot be imported, configured, registered, or tracked.

pub fn add_python_actor_instance( &mut self, actor: &Py<PyAny>, actor_id: ActorId, ) -> Result<()>

Adds a constructed Python actor instance to the trader under actor_id.

The actor must already be configured; this runs the registration sequence every Python actor needs and rolls back everything the attempt created if any step fails.

Errors

Returns an error if the trader already tracks a component under the actor’s ID, or if the actor cannot be registered or tracked.

pub fn add_controller_from_importable_config( trader: &Rc<RefCell<Self>>, config: &ImportableControllerConfig, ) -> Result<ActorId>

Adds an importable Python controller to the trader.

Errors

Returns an error if the controller cannot be imported, configured, registered, or tracked.

pub fn add_strategy_from_importable_config( &mut self, config: &ImportableStrategyConfig, ) -> Result<StrategyId>

Adds an importable Python strategy to the trader.

Errors

Returns an error if the strategy cannot be imported, configured, registered, or tracked.

pub fn add_python_strategy_instance( &mut self, strategy: &Py<PyAny>, ) -> Result<StrategyId>

Adds a constructed Python strategy instance to the trader.

This is the instance-based counterpart to Self::add_strategy_from_importable_config: the strategy is already constructed in Python, avoiding the dict-to-JSON round trip of the importable-config path. The strategy ID, order ID tag, and logging flags are sourced from the instance’s retained .config.

Errors

Returns an error if the strategy cannot be configured, registered, or tracked.

pub fn prepare_python_strategy_instance( &mut self, strategy: &Py<PyAny>, ) -> Result<StrategyId>

Prepares a constructed Python strategy instance for registration without committing it.

Errors

Returns an error if the strategy cannot be configured, or its ID or order ID tag is already registered.

pub fn commit_python_strategy_instance( &mut self, strategy: &Py<PyAny>, ) -> Result<StrategyId>

Commits a previously prepared Python strategy instance.

Errors

Returns an error if the trader already tracks a component under the strategy’s ID, or if the strategy cannot be registered or its subscriptions cannot be installed.

pub fn add_py_execution_algorithm_instance( &mut self, algorithm: PyExecutionAlgorithm, wrapper: &Py<PyAny>, ) -> Result<ExecAlgorithmId>

Adds a constructed [PyExecutionAlgorithm] instance to the trader.

wrapper is the Python object which owns algorithm; the trader’s registries keep it alive for as long as the algorithm stays registered.

Errors

Returns an error if the trader already tracks a component under the algorithm’s ID, or if the algorithm cannot be registered or tracked.

pub fn add_python_exec_algorithm_instance( &mut self, exec_algorithm: &Py<PyAny>, actor_id: ActorId, ) -> Result<ExecAlgorithmId>

Adds a constructed Python actor instance to the trader as an execution algorithm.

This is the [PyDataActor]-backed execution algorithm path, used when the Python class derives from DataActor rather than ExecutionAlgorithm.

Errors

Returns an error if the trader already tracks a component under the algorithm’s ID, or if the algorithm cannot be registered or tracked.

Trait Implementations

impl Component for Trader

fn component_id(&self) -> ComponentId

Returns the unique identifier for this component.

fn state(&self) -> ComponentState

Returns the current state of the component.

fn transition_state(&mut self, trigger: ComponentTrigger) -> Result<()>

Transition the component with the state trigger.

fn register( &mut self, _trader_id: TraderId, _clock: Rc<RefCell<dyn Clock>>, _cache: Rc<RefCell<Cache>>, ) -> Result<()>

Registers the component with a system.

fn on_start(&mut self) -> Result<()>

Actions to be performed on start.

fn on_stop(&mut self) -> Result<()>

Actions to be performed on stop.

fn on_reset(&mut self) -> Result<()>

Actions to be performed on reset.

fn on_dispose(&mut self) -> Result<()>

Actions to be performed on dispose.

fn is_ready(&self) -> bool

Returns whether the component is ready.

fn not_running(&self) -> bool

Returns whether the component is not running.

fn is_running(&self) -> bool

Returns whether the component is running.

fn is_stopped(&self) -> bool

Returns whether the component is stopped.

fn is_degraded(&self) -> bool

Returns whether the component has been degraded.

fn is_faulted(&self) -> bool

Returns whether the component has been faulted.

fn is_disposed(&self) -> bool

Returns whether the component has been disposed.

fn initialize(&mut self) -> Result<(), Error>

Initializes the component.

fn start(&mut self) -> Result<(), Error>

Starts the component.

fn stop(&mut self) -> Result<(), Error>

Stops the component.

fn resume(&mut self) -> Result<(), Error>

Resumes the component.

fn degrade(&mut self) -> Result<(), Error>

Degrades the component.

fn fault(&mut self) -> Result<(), Error>

Faults the component.

fn reset(&mut self) -> Result<(), Error>

Resets the component to its initial state.

fn dispose(&mut self) -> Result<(), Error>

Disposes of the component, releasing any resources.

fn release_subscriptions(&mut self)

Releases the message bus registrations this component installed.

fn on_resume(&mut self) -> Result<(), Error>

Actions to be performed on resume.

fn on_degrade(&mut self) -> Result<(), Error>

Actions to be performed on degrade.

fn on_fault(&mut self) -> Result<(), Error>

Actions to be performed on fault.

impl Debug for Trader

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

Formats the value using the given formatter.