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.

Clock System and Time Management

Relevant Rust source files

crates/common/src/clock.rs
crates/common/src/live/clock.rs
crates/system/src/clock_factory.rs
crates/core/src/nanos.rs

This document describes the clock system and time management infrastructure in NautilusTrader. The clock system provides unified time interfaces for both backtesting (deterministic time) and live trading (real-time), supporting nanosecond precision timestamps and flexible timer callback mechanisms.

Purpose and Scope

The clock system serves two critical functions:

Time source abstraction: Provides a unified API for obtaining current time across backtest and live contexts via the Clock trait
Timer management: Enables components to schedule future callbacks via time alerts and repeating timers

The system ensures that strategies and components can use identical time-related code in both backtesting (with manually controlled time) and live trading (with real system time), maintaining the platform's core principle of research-to-production parity.

Clock Type Hierarchy

NautilusTrader implements two concrete Rust clock types behind the common Clock trait: deterministic TestClock and real-time LiveClock.

Entity Relationship Diagram

Backtest and live environments using TestClock and LiveClock around the same Nautilus model and engine semantics.

Both clocks implement timestamp, UTC, timer enumeration, time-alert, repeating-timer, cancellation, and default-handler operations. TestClock additionally exposes controlled time advancement for deterministic simulation; LiveClock advances from the system clock and dispatches real-time timers.

Base Clock Interface

The Clock trait defines the common interface for all clock implementations

Timestamp Methods

All clocks provide multiple timestamp precision levels, derived from a 64-bit nanosecond integer wrapped in the UnixNanos type:

Method	Return Type	Description	Precision
`timestamp()`	`f64`	UNIX timestamp in seconds	Floating point
`timestamp_ms()`	`u64`	UNIX timestamp in milliseconds	1 millisecond
`timestamp_us()`	`u64`	UNIX timestamp in microseconds	1 microsecond
`timestamp_ns()`	`UnixNanos`	UNIX timestamp in nanoseconds	1 nanosecond

AtomicTime and Monotonicity

The system uses AtomicTime to manage thread-safe time updates.

Real-time mode: Uses atomic operations to ensure strictly increasing timestamps even if the system clock drifts.
Static mode: Uses acquire/release semantics for manual updates in simulations via set_time or increment_time

TestClock: Deterministic Time for Backtesting

The TestClock provides a static, manually controlled clock for backtesting and unit testing. It only advances when explicitly instructed

Key Characteristics

Deterministic: Time only advances via explicit calls like set_time or increment_time
Priority Queue: Uses a BTreeMap to manage scheduled events by timestamp, ensuring they fire in the correct order
Synchronous Execution: Callbacks in TestClock are executed synchronously during the time advancement phase as the clock reaches scheduled event times.

LiveClock: Real-Time for Live Trading

The LiveClock uses system time to provide real-time timestamps for live trading environments

Key Characteristics

System Time Based: Queries the actual system clock.
Monotonic Guarantees: Timestamps are guaranteed to be unique and monotonically increasing.
Asynchronous Timers: Schedules alerts that fire based on real-world elapsed time using the system's asynchronous event loop.

Timer System

Both clock types support scheduling future callbacks via TimeEventCallback

Callback Types

NautilusTrader supports multiple callback execution contexts :

Callback: Executes a registered Rust callback through the clock callback registry.
Rust: Thread-safe callbacks (Send + Sync) using Arc
RustLocal: Single-threaded callbacks using Rc for capturing local state like RefCell

Time Alerts and Repeating Timers

Time Alerts: A one-time event scheduled for a specific timestamp via set_time_alert_ns
Repeating Timers: An event that fires at regular intervals via set_timer_ns

TimeEvent Structure

When a timer fires, it produces a TimeEvent :

name: Identifier of the timer (as a Ustr)
event_id: Unique UUID4 for the event
ts_event: The scheduled execution time (UnixNanos)
ts_init: The actual creation time of the event instance

Throttler and Rate Limiting

The Throttler component controls the rate of message processing to prevent venue rate-limit breaches or system overload

Throttler Logic

RateLimit: Defines a limit (count) and an interval_ns (nanoseconds)
Buffering: If the limit is reached, messages are stored in a VecDeque<T> buffer
Leaky Bucket: It tracks message timestamps in a VecDeque<UnixNanos> to enforce the sliding window
Integration: Used extensively in the RiskEngine to throttle order submissions and modifications

Builder Patterns and Factories

For live and sandbox nodes, the system provides builder methods to inject the appropriate clock implementation.

with_clock_factory

The with_clock_factory pattern is used in node builders (like LiveNode or SandboxNode) to allow the system to instantiate the correct Clock type during the initialization phase. This ensures that even when running in a "sandbox" (live components with a test clock), the dependency injection is handled correctly.

Summary Table: Time Constants

The system defines standard nanosecond-based constants for calculations.

Constant	Value (Nanoseconds)
`NANOSECONDS_IN_MICROSECOND`	1,000
`NANOSECONDS_IN_MILLISECOND`	1,000,000
`NANOSECONDS_IN_SECOND`	1,000,000,000
`NANOSECONDS_IN_MINUTE`	60,000,000,000
`NANOSECONDS_IN_DAY`	86,400,000,000,000