Skip to main content

nautilus_common/
runner.rs

1// -------------------------------------------------------------------------------------------------
2//  Copyright (C) 2015-2026 Nautech Systems Pty Ltd. All rights reserved.
3//  https://nautechsystems.io
4//
5//  Licensed under the GNU Lesser General Public License Version 3.0 (the "License");
6//  You may not use this file except in compliance with the License.
7//  You may obtain a copy of the License at https://www.gnu.org/licenses/lgpl-3.0.en.html
8//
9//  Unless required by applicable law or agreed to in writing, software
10//  distributed under the License is distributed on an "AS IS" BASIS,
11//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12//  See the License for the specific language governing permissions and
13//  limitations under the License.
14// -------------------------------------------------------------------------------------------------
15
16//! Global runtime machinery and thread-local storage.
17//!
18//! This module provides global access to shared runtime resources including clocks,
19//! message queues, and time event channels. It manages thread-local storage for
20//! system-wide components that need to be accessible across threads.
21
22use std::{
23    cell::RefCell,
24    fmt::{Debug, Display},
25    num::NonZeroU64,
26    sync::{
27        Arc, Weak,
28        atomic::{AtomicU64, AtomicUsize, Ordering},
29    },
30    thread::{self, ThreadId},
31};
32
33use ahash::AHashMap;
34
35use crate::{
36    actor::ChainContext,
37    messages::{data::DataCommand, execution::TradingCommand},
38    msgbus::{self, Endpoint, MStr, MessagingSwitchboard},
39    timer::{TimeEvent, TimeEventCallback, TimeEventHandler},
40};
41
42const CALLBACK_CLOSED: usize = 1 << (usize::BITS - 1);
43const CALLBACK_LEASES: usize = CALLBACK_CLOSED - 1;
44static NEXT_TIME_EVENT_CALLBACK_ID: AtomicU64 = AtomicU64::new(1);
45
46/// A monitored message channel feeding the runner event loop.
47///
48/// Each variant identifies an engine-facing channel tracked by the queue monitor.
49#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
50#[cfg_attr(
51    feature = "python",
52    pyo3::pyclass(
53        frozen,
54        eq,
55        eq_int,
56        module = "nautilus_trader.common",
57        from_py_object,
58        rename_all = "SCREAMING_SNAKE_CASE",
59    )
60)]
61#[cfg_attr(
62    feature = "python",
63    pyo3_stub_gen::derive::gen_stub_pyclass_enum(module = "nautilus_trader.common")
64)]
65pub enum SystemChannel {
66    TimeEvents,
67    ExecEvents,
68    ExecCommands,
69    DataEvents,
70    DataCommands,
71}
72
73#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
74struct TimeEventCallbackId(NonZeroU64);
75
76#[derive(Debug)]
77struct TimeEventCallbackTokenInner {
78    id: TimeEventCallbackId,
79    owner: ThreadId,
80    state: AtomicUsize,
81}
82
83struct TimeEventCallbackEntry {
84    callback: TimeEventCallback,
85    token: Weak<TimeEventCallbackTokenInner>,
86}
87
88/// A send-safe handle to a thread-local time event callback.
89#[derive(Clone, Debug)]
90pub(crate) struct TimeEventCallbackToken(Arc<TimeEventCallbackTokenInner>);
91
92impl TimeEventCallbackToken {
93    fn register(callback: TimeEventCallback) -> Self {
94        debug_assert!(callback.is_local());
95        purge_closed_time_event_callbacks();
96
97        let raw_id = NEXT_TIME_EVENT_CALLBACK_ID.fetch_add(1, Ordering::Relaxed);
98        let id = TimeEventCallbackId(
99            NonZeroU64::new(raw_id).expect("time event callback IDs exhausted"),
100        );
101        let token = Self(Arc::new(TimeEventCallbackTokenInner {
102            id,
103            owner: thread::current().id(),
104            state: AtomicUsize::new(0),
105        }));
106        TIME_EVENT_CALLBACKS.with(|callbacks| {
107            let previous = callbacks.borrow_mut().insert(
108                id,
109                TimeEventCallbackEntry {
110                    callback,
111                    token: Arc::downgrade(&token.0),
112                },
113            );
114            debug_assert!(previous.is_none());
115        });
116        token
117    }
118
119    pub(crate) fn acquire(&self) -> Option<TimeEventCallbackLease> {
120        let mut state = self.0.state.load(Ordering::Acquire);
121        loop {
122            if state & CALLBACK_CLOSED != 0 {
123                return None;
124            }
125            let leases = state & CALLBACK_LEASES;
126            assert!(
127                leases < CALLBACK_LEASES,
128                "time event callback lease count overflow"
129            );
130
131            match self.0.state.compare_exchange_weak(
132                state,
133                state + 1,
134                Ordering::AcqRel,
135                Ordering::Acquire,
136            ) {
137                Ok(_) => return Some(TimeEventCallbackLease(self.0.clone())),
138                Err(actual) => state = actual,
139            }
140        }
141    }
142
143    #[cfg(any(feature = "live", test))]
144    pub(crate) fn is_closed(&self) -> bool {
145        self.0.state.load(Ordering::Acquire) & CALLBACK_CLOSED != 0
146    }
147
148    pub(crate) fn close(&self) {
149        let previous = self.0.state.fetch_or(CALLBACK_CLOSED, Ordering::AcqRel);
150        if previous & CALLBACK_LEASES == 0 {
151            self.remove_on_owner_thread();
152        }
153    }
154
155    fn remove_on_owner_thread(&self) {
156        if self.0.owner == thread::current().id() {
157            // Reachable from `Drop` (`LiveTimer::drop` -> `close`), which can
158            // run during thread-local teardown when `TIME_EVENT_CALLBACKS` is
159            // already destroyed. `try_with` returns `AccessError` rather than
160            // panicking (a panic in a TLS destructor aborts the process); the
161            // map is being torn down, so the removal is moot. The removed
162            // entry is returned out of the closure and dropped after the
163            // `RefMut` is released. Never log here: the logging TLS may also
164            // be in teardown.
165            let _ = TIME_EVENT_CALLBACKS
166                .try_with(|callbacks| callbacks.borrow_mut().remove(&self.0.id));
167        }
168    }
169
170    #[cfg(test)]
171    fn is_registered(&self) -> bool {
172        TIME_EVENT_CALLBACKS.with(|callbacks| callbacks.borrow().contains_key(&self.0.id))
173    }
174}
175
176/// A per-message hold on a registered callback entry.
177///
178/// The final lease of a closed token removes the TLS entry when it drops on
179/// the owner thread. A final lease dropped on another thread (failed send,
180/// receiver shutdown on a foreign thread) cannot touch the owner's TLS map;
181/// the closed entry is then reclaimed lazily by the next owner-thread
182/// registration or [`purge_closed_time_event_callbacks`] call (`LiveClock`
183/// invokes the latter from `clear_expired_timers`). That is bounded
184/// retention of the callback, never a leak across registrations and never
185/// a cross-thread `Rc` access.
186#[derive(Debug)]
187pub(crate) struct TimeEventCallbackLease(Arc<TimeEventCallbackTokenInner>);
188
189impl Drop for TimeEventCallbackLease {
190    fn drop(&mut self) {
191        let previous = self.0.state.fetch_sub(1, Ordering::AcqRel);
192        debug_assert!(previous & CALLBACK_LEASES > 0);
193        if previous == CALLBACK_CLOSED | 1 && self.0.owner == thread::current().id() {
194            // As in `remove_on_owner_thread`, this final lease can drop during
195            // thread-local teardown with `TIME_EVENT_CALLBACKS` already gone;
196            // `try_with` keeps the destructor from aborting the process.
197            let _ = TIME_EVENT_CALLBACKS
198                .try_with(|callbacks| callbacks.borrow_mut().remove(&self.0.id));
199        }
200    }
201}
202
203#[derive(Clone)]
204enum SendTimeEventCallback {
205    #[cfg(feature = "python")]
206    Python(Arc<crate::timer::PythonTimeEventCallback>),
207    Rust(Arc<dyn Fn(TimeEvent) + Send + Sync>),
208}
209
210impl Debug for SendTimeEventCallback {
211    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
212        match self {
213            #[cfg(feature = "python")]
214            Self::Python(_) => f.write_str("Python callback"),
215            Self::Rust(_) => f.write_str("Rust callback (thread-safe)"),
216        }
217    }
218}
219
220impl SendTimeEventCallback {
221    fn into_callback(self) -> TimeEventCallback {
222        match self {
223            #[cfg(feature = "python")]
224            Self::Python(callback) => TimeEventCallback::Python(callback),
225            Self::Rust(callback) => TimeEventCallback::Rust(callback),
226        }
227    }
228}
229
230#[derive(Clone, Debug)]
231#[cfg(feature = "live")]
232pub(crate) struct TimeEventMessageFactory(SendTimeEventCallback);
233
234#[cfg(feature = "live")]
235impl TimeEventMessageFactory {
236    pub(crate) fn new(callback: &TimeEventCallback) -> Self {
237        match callback {
238            #[cfg(feature = "python")]
239            TimeEventCallback::Python(callback) => {
240                Self(SendTimeEventCallback::Python(callback.clone()))
241            }
242            TimeEventCallback::Rust(callback) => {
243                Self(SendTimeEventCallback::Rust(callback.clone()))
244            }
245            TimeEventCallback::RustLocal(_) => {
246                unreachable!("RustLocal callbacks require registered dispatch")
247            }
248        }
249    }
250
251    pub(crate) fn message(&self, event: TimeEvent) -> TimeEventMessage {
252        TimeEventMessage {
253            event,
254            dispatch: TimeEventDispatch::Direct(self.0.clone()),
255        }
256    }
257}
258
259#[derive(Debug)]
260enum TimeEventDispatch {
261    Direct(SendTimeEventCallback),
262    Registered(TimeEventCallbackLease),
263    #[cfg(any(feature = "live", test))]
264    Cleanup(TimeEventCallbackLease),
265}
266
267/// A send-safe live time event channel payload.
268///
269/// The dispatch representation is private so local callbacks can never be
270/// embedded in a cross-thread message.
271#[derive(Debug)]
272pub struct TimeEventMessage {
273    event: TimeEvent,
274    dispatch: TimeEventDispatch,
275}
276
277impl TimeEventMessage {
278    /// Creates a message from a time event and callback.
279    ///
280    /// # Panics
281    ///
282    /// Panics if the process-wide callback ID or lease count is exhausted.
283    #[must_use]
284    pub fn new(event: TimeEvent, callback: TimeEventCallback) -> Self {
285        match callback {
286            #[cfg(feature = "python")]
287            TimeEventCallback::Python(callback) => Self {
288                event,
289                dispatch: TimeEventDispatch::Direct(SendTimeEventCallback::Python(callback)),
290            },
291            TimeEventCallback::Rust(callback) => Self {
292                event,
293                dispatch: TimeEventDispatch::Direct(SendTimeEventCallback::Rust(callback)),
294            },
295            callback @ TimeEventCallback::RustLocal(_) => {
296                let token = TimeEventCallbackToken::register(callback);
297                let lease = token
298                    .acquire()
299                    .expect("new time event callback token should be open");
300                token.close();
301                Self::registered(event, lease)
302            }
303        }
304    }
305
306    /// Returns the time event carried by this message.
307    #[must_use]
308    pub const fn event(&self) -> &TimeEvent {
309        &self.event
310    }
311
312    pub(crate) const fn registered(event: TimeEvent, lease: TimeEventCallbackLease) -> Self {
313        Self {
314            event,
315            dispatch: TimeEventDispatch::Registered(lease),
316        }
317    }
318
319    #[cfg(any(feature = "live", test))]
320    pub(crate) const fn cleanup(event: TimeEvent, lease: TimeEventCallbackLease) -> Self {
321        Self {
322            event,
323            dispatch: TimeEventDispatch::Cleanup(lease),
324        }
325    }
326
327    /// Resolves and runs this message on the receiving thread.
328    ///
329    /// Messages for a `RustLocal` callback must be dispatched on the thread
330    /// where the callback was registered. Dispatching them elsewhere drops
331    /// the event and returns `false`.
332    ///
333    /// Returns `true` when a callback was dispatched. Cleanup messages and
334    /// wrong-thread registered messages return `false`.
335    pub fn dispatch(self) -> bool {
336        let Self { event, dispatch } = self;
337        match dispatch {
338            TimeEventDispatch::Direct(callback) => {
339                TimeEventHandler::new(event, callback.into_callback()).run();
340                true
341            }
342            TimeEventDispatch::Registered(lease) => {
343                if lease.0.owner != thread::current().id() {
344                    log::error!(
345                        "Dropping time event '{}' drained outside its callback owner thread",
346                        event.name
347                    );
348                    return false;
349                }
350                let callback = TIME_EVENT_CALLBACKS.with(|callbacks| {
351                    callbacks
352                        .borrow()
353                        .get(&lease.0.id)
354                        .map(|entry| entry.callback.clone())
355                });
356
357                if let Some(callback) = callback {
358                    TimeEventHandler::new(event, callback).run();
359                    true
360                } else {
361                    log::error!("Dropping time event with an unregistered callback token");
362                    false
363                }
364            }
365            #[cfg(any(feature = "live", test))]
366            TimeEventDispatch::Cleanup(lease) => {
367                if lease.0.owner != thread::current().id() {
368                    log::error!("Dropping timer cleanup message outside its callback owner thread");
369                }
370                false
371            }
372        }
373    }
374}
375
376#[cfg(any(feature = "live", test))]
377pub(crate) fn register_time_event_callback(callback: TimeEventCallback) -> TimeEventCallbackToken {
378    TimeEventCallbackToken::register(callback)
379}
380
381pub(crate) fn purge_closed_time_event_callbacks() {
382    TIME_EVENT_CALLBACKS.with(|callbacks| {
383        callbacks.borrow_mut().retain(|_, entry| {
384            entry
385                .token
386                .upgrade()
387                .is_some_and(|token| token.state.load(Ordering::Acquire) != CALLBACK_CLOSED)
388        });
389    });
390}
391
392/// Trait for data command sending that can be implemented for both sync and async runners.
393pub trait DataCommandSender {
394    /// Executes a data command.
395    ///
396    /// - **Sync runners** send the command to a queue for synchronous execution.
397    /// - **Async runners** send the command to a channel for asynchronous execution.
398    fn execute(&self, command: DataCommand);
399}
400
401/// Synchronous [`DataCommandSender`] for backtest environments.
402///
403/// Buffers commands in a thread-local queue for deferred execution,
404/// avoiding `RefCell` re-entrancy when sent from event handler callbacks.
405#[derive(Debug)]
406pub struct SyncDataCommandSender;
407
408impl DataCommandSender for SyncDataCommandSender {
409    fn execute(&self, command: DataCommand) {
410        let command = QueuedDataCommand {
411            command: Some(command),
412            context: ChainContext::capture(),
413        };
414
415        DATA_CMD_QUEUE.with(|q| q.borrow_mut().push(command));
416    }
417}
418
419/// Drains all buffered data commands, dispatching each to the data engine.
420///
421/// Commands enqueued by handlers stay queued for a subsequent drain.
422///
423/// # Panics
424///
425/// Panics if a command handler panics; remaining commands in the collected batch are then dropped.
426pub fn drain_data_cmd_queue() {
427    DATA_CMD_QUEUE.with(|q| {
428        // Skip the drain batch when empty; backtest replay calls this per data point
429        if q.borrow().is_empty() {
430            return;
431        }
432
433        let commands: Vec<QueuedDataCommand> = q.borrow_mut().drain(..).collect();
434        let endpoint = MessagingSwitchboard::data_engine_execute();
435
436        for mut queued in commands {
437            let command = queued.command.take().expect("queued command is present");
438            queued
439                .context
440                .with_chain(|| msgbus::send_data_command(endpoint, command));
441        }
442    });
443}
444
445struct QueuedDataCommand {
446    command: Option<DataCommand>,
447    context: ChainContext,
448}
449
450impl Drop for QueuedDataCommand {
451    fn drop(&mut self) {
452        if self.command.is_some() {
453            self.context.with_chain(|| drop(self.command.take()));
454        }
455    }
456}
457
458/// Returns `true` if the data command queue is empty.
459pub fn data_cmd_queue_is_empty() -> bool {
460    DATA_CMD_QUEUE.with(|q| q.borrow().is_empty())
461}
462
463/// Discards the current synchronous data and trading command batches without executing them.
464///
465/// Queue borrows end before captures are destroyed. Commands emitted by capture destruction remain
466/// queued; callers must establish a safe teardown boundary before discarding work.
467pub fn clear_command_queues() {
468    let data = DATA_CMD_QUEUE.with(|queue| std::mem::take(&mut *queue.borrow_mut()));
469    let trading = TRADING_CMD_QUEUE.with(|queue| std::mem::take(&mut *queue.borrow_mut()));
470    drop(data);
471    drop(trading);
472}
473
474/// Gets the global data command sender.
475///
476/// # Panics
477///
478/// Panics if the sender is uninitialized.
479#[must_use]
480pub fn get_data_cmd_sender() -> Arc<dyn DataCommandSender> {
481    DATA_CMD_SENDER.with(|sender| {
482        sender
483            .borrow()
484            .as_ref()
485            .expect("Data command sender should be initialized by runner")
486            .clone()
487    })
488}
489
490/// Sets the global data command sender.
491///
492/// This should be called by the runner when it initializes.
493/// Can only be called once per thread.
494///
495/// # Panics
496///
497/// Panics if a sender has already been set.
498pub fn set_data_cmd_sender(sender: Arc<dyn DataCommandSender>) {
499    DATA_CMD_SENDER.with(|s| {
500        let mut slot = s.borrow_mut();
501        assert!(slot.is_none(), "Data command sender can only be set once");
502        *slot = Some(sender);
503    });
504}
505
506/// Replaces the global data command sender for the current thread.
507pub fn replace_data_cmd_sender(sender: Arc<dyn DataCommandSender>) {
508    DATA_CMD_SENDER.with(|s| {
509        *s.borrow_mut() = Some(sender);
510    });
511}
512
513/// Trait for time event sending that can be implemented for both sync and async runners.
514///
515/// Implementations may transfer messages across threads, but messages for
516/// `RustLocal` callbacks must be dispatched on the callback's owner thread.
517pub trait TimeEventSender: Debug + Send + Sync {
518    /// Sends a live time event message.
519    fn send(&self, message: TimeEventMessage);
520}
521
522/// Gets the global time event sender.
523///
524/// # Panics
525///
526/// Panics if the sender is uninitialized.
527#[must_use]
528pub fn get_time_event_sender() -> Arc<dyn TimeEventSender> {
529    TIME_EVENT_SENDER.with(|sender| {
530        sender
531            .borrow()
532            .as_ref()
533            .expect("Time event sender should be initialized by runner")
534            .clone()
535    })
536}
537
538/// Attempts to get the global time event sender without panicking.
539///
540/// Returns `None` if the sender is not initialized (e.g., in test environments).
541#[must_use]
542pub fn try_get_time_event_sender() -> Option<Arc<dyn TimeEventSender>> {
543    TIME_EVENT_SENDER.with(|sender| sender.borrow().as_ref().cloned())
544}
545
546/// Sets the global time event sender.
547///
548/// Can only be called once per thread.
549///
550/// # Panics
551///
552/// Panics if a sender has already been set.
553pub fn set_time_event_sender(sender: Arc<dyn TimeEventSender>) {
554    TIME_EVENT_SENDER.with(|s| {
555        let mut slot = s.borrow_mut();
556        assert!(slot.is_none(), "Time event sender can only be set once");
557        *slot = Some(sender);
558    });
559}
560
561/// Replaces the global time event sender for the current thread.
562pub fn replace_time_event_sender(sender: Arc<dyn TimeEventSender>) {
563    TIME_EVENT_SENDER.with(|s| {
564        *s.borrow_mut() = Some(sender);
565    });
566}
567
568/// A deferred trading command and its direct endpoint.
569#[derive(Debug)]
570pub struct TradingCommandMessage {
571    endpoint: MStr<Endpoint>,
572    command: TradingCommand,
573}
574
575impl TradingCommandMessage {
576    /// Creates a deferred trading command message.
577    #[must_use]
578    pub const fn new(endpoint: MStr<Endpoint>, command: TradingCommand) -> Self {
579        Self { endpoint, command }
580    }
581
582    /// Returns the trading command carried by this message.
583    #[must_use]
584    pub const fn command(&self) -> &TradingCommand {
585        &self.command
586    }
587
588    /// Returns the direct endpoint carried by this message.
589    #[must_use]
590    pub const fn endpoint(&self) -> MStr<Endpoint> {
591        self.endpoint
592    }
593
594    /// Dispatches the command and returns commands deferred by the endpoint handler.
595    #[must_use]
596    pub fn dispatch(self) -> Vec<Self> {
597        let TradingCommandDispatch::Unscoped(messages) =
598            self.dispatch_with(TradingCommandDispatch::Unscoped(Vec::new()))
599        else {
600            unreachable!("unscoped dispatch returns unscoped commands");
601        };
602
603        messages
604    }
605
606    fn dispatch_with(self, dispatch: TradingCommandDispatch) -> TradingCommandDispatch {
607        let guard = TradingCommandDispatchGuard::new(dispatch);
608        msgbus::send_trading_command(self.endpoint, self.command);
609        guard.finish()
610    }
611}
612
613impl Display for TradingCommandMessage {
614    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
615        write!(
616            f,
617            "TradingCommandMessage(endpoint={}, command={})",
618            self.endpoint, self.command
619        )
620    }
621}
622
623enum TradingCommandDispatch {
624    Unscoped(Vec<TradingCommandMessage>),
625    Sync(Vec<QueuedTradingCommand>),
626}
627
628struct TradingCommandDispatchGuard {
629    active: bool,
630}
631
632impl TradingCommandDispatchGuard {
633    fn new(dispatch: TradingCommandDispatch) -> Self {
634        TRADING_CMD_DISPATCHES.with(|dispatches| dispatches.borrow_mut().push(dispatch));
635        Self { active: true }
636    }
637
638    fn finish(mut self) -> TradingCommandDispatch {
639        self.active = false;
640        TRADING_CMD_DISPATCHES.with(|dispatches| {
641            dispatches
642                .borrow_mut()
643                .pop()
644                .expect("trading command dispatch should be active")
645        })
646    }
647}
648
649impl Drop for TradingCommandDispatchGuard {
650    fn drop(&mut self) {
651        if self.active {
652            let dispatch = TRADING_CMD_DISPATCHES.with(|dispatches| dispatches.borrow_mut().pop());
653            drop(dispatch);
654        }
655    }
656}
657
658/// Returns `true` while a deferred trading command is being dispatched.
659#[must_use]
660pub fn trading_cmd_is_dispatching() -> bool {
661    TRADING_CMD_DISPATCHES.with(|dispatches| !dispatches.borrow().is_empty())
662}
663
664/// Captures a trading command for dispatch after the current endpoint handler returns.
665///
666/// # Panics
667///
668/// Panics if no deferred trading command is being dispatched.
669pub fn capture_trading_cmd(message: TradingCommandMessage) {
670    TRADING_CMD_DISPATCHES.with(|dispatches| {
671        match dispatches
672            .borrow_mut()
673            .last_mut()
674            .expect("trading command dispatch should be active")
675        {
676            TradingCommandDispatch::Unscoped(messages) => messages.push(message),
677            TradingCommandDispatch::Sync(messages) => {
678                messages.push(QueuedTradingCommand::new(message));
679            }
680        }
681    });
682}
683
684/// Trait for trading command sending that can be implemented for both sync and async runners.
685pub trait TradingCommandSender {
686    /// Defers a trading command message.
687    ///
688    /// - **Sync runners** enqueue the message for synchronous execution.
689    /// - **Async runners** send the message to a channel for asynchronous execution.
690    ///
691    /// Runners dispatch each message to the direct endpoint it carries.
692    fn execute(&self, message: TradingCommandMessage);
693}
694
695/// Synchronous [`TradingCommandSender`] for backtest environments.
696///
697/// Buffers commands in a thread-local queue for deferred execution,
698/// avoiding `RefCell` re-entrancy when sent from event handler callbacks.
699#[derive(Debug)]
700pub struct SyncTradingCommandSender;
701
702impl TradingCommandSender for SyncTradingCommandSender {
703    fn execute(&self, message: TradingCommandMessage) {
704        let queued = QueuedTradingCommand::new(message);
705        TRADING_CMD_QUEUE.with(|q| q.borrow_mut().push(queued));
706    }
707}
708
709/// Drains all buffered trading commands to their direct endpoints.
710///
711/// Deferred children run depth-first before the next command in the collected batch.
712/// Commands enqueued by handlers stay queued for a subsequent drain.
713///
714/// # Panics
715///
716/// Panics if a command handler panics; pending children and the remaining batch are then dropped.
717pub fn drain_trading_cmd_queue() {
718    TRADING_CMD_QUEUE.with(|q| {
719        // Skip the drain batch when empty; backtest replay calls this per data point
720        if q.borrow().is_empty() {
721            return;
722        }
723
724        let messages: Vec<QueuedTradingCommand> = q.borrow_mut().drain(..).collect();
725        for message in messages {
726            dispatch_trading_cmd(message, &mut |_| {});
727        }
728    });
729}
730
731#[cfg(feature = "live")]
732pub(crate) fn dispatch_scoped_trading_command(
733    message: TradingCommandMessage,
734    context: ChainContext,
735    mut before: impl FnMut(&TradingCommandMessage),
736) {
737    dispatch_trading_cmd(
738        QueuedTradingCommand {
739            message: Some(message),
740            context,
741        },
742        &mut before,
743    );
744}
745
746fn dispatch_trading_cmd(
747    message: QueuedTradingCommand,
748    before: &mut impl FnMut(&TradingCommandMessage),
749) {
750    // Reuse the child buffer so leaf commands need no traversal allocation
751    let mut messages = message.dispatch(before);
752    messages.reverse();
753    while let Some(message) = messages.pop() {
754        messages.extend(message.dispatch(before).into_iter().rev());
755    }
756}
757
758struct QueuedTradingCommand {
759    message: Option<TradingCommandMessage>,
760    context: ChainContext,
761}
762
763impl QueuedTradingCommand {
764    fn new(message: TradingCommandMessage) -> Self {
765        Self {
766            message: Some(message),
767            context: ChainContext::capture(),
768        }
769    }
770
771    fn dispatch(mut self, before: &mut impl FnMut(&TradingCommandMessage)) -> Vec<Self> {
772        let message = self.message.take().expect("queued command is present");
773        self.context.with_chain(|| {
774            before(&message);
775
776            let TradingCommandDispatch::Sync(messages) =
777                message.dispatch_with(TradingCommandDispatch::Sync(Vec::new()))
778            else {
779                unreachable!("synchronous dispatch returns scoped commands");
780            };
781
782            messages
783        })
784    }
785}
786
787impl Drop for QueuedTradingCommand {
788    fn drop(&mut self) {
789        if self.message.is_some() {
790            self.context.with_chain(|| drop(self.message.take()));
791        }
792    }
793}
794
795/// Returns `true` if the trading command queue is empty.
796pub fn trading_cmd_queue_is_empty() -> bool {
797    TRADING_CMD_QUEUE.with(|q| q.borrow().is_empty())
798}
799
800/// Gets the global trading command sender.
801///
802/// # Panics
803///
804/// Panics if the sender is uninitialized.
805#[must_use]
806pub fn get_trading_cmd_sender() -> Arc<dyn TradingCommandSender> {
807    EXEC_CMD_SENDER.with(|sender| {
808        sender
809            .borrow()
810            .as_ref()
811            .expect("Trading command sender should be initialized by runner")
812            .clone()
813    })
814}
815
816/// Attempts to get the global trading command sender without panicking.
817///
818/// Returns `None` if the sender is not initialized (e.g., in test environments).
819#[must_use]
820pub fn try_get_trading_cmd_sender() -> Option<Arc<dyn TradingCommandSender>> {
821    EXEC_CMD_SENDER.with(|sender| sender.borrow().as_ref().cloned())
822}
823
824/// Sets the global trading command sender.
825///
826/// This should be called by the runner when it initializes.
827/// Can only be called once per thread.
828///
829/// # Panics
830///
831/// Panics if a sender has already been set.
832pub fn set_exec_cmd_sender(sender: Arc<dyn TradingCommandSender>) {
833    EXEC_CMD_SENDER.with(|s| {
834        let mut slot = s.borrow_mut();
835        assert!(
836            slot.is_none(),
837            "Trading command sender can only be set once"
838        );
839        *slot = Some(sender);
840    });
841}
842
843/// Replaces the global trading command sender for the current thread.
844pub fn replace_exec_cmd_sender(sender: Arc<dyn TradingCommandSender>) {
845    EXEC_CMD_SENDER.with(|s| {
846        *s.borrow_mut() = Some(sender);
847    });
848}
849
850thread_local! {
851    static TIME_EVENT_CALLBACKS: RefCell<AHashMap<TimeEventCallbackId, TimeEventCallbackEntry>> = RefCell::new(AHashMap::new());
852    static TIME_EVENT_SENDER: RefCell<Option<Arc<dyn TimeEventSender>>> = const { RefCell::new(None) };
853    static DATA_CMD_SENDER: RefCell<Option<Arc<dyn DataCommandSender>>> = const { RefCell::new(None) };
854    static EXEC_CMD_SENDER: RefCell<Option<Arc<dyn TradingCommandSender>>> = const { RefCell::new(None) };
855    static DATA_CMD_QUEUE: RefCell<Vec<QueuedDataCommand>> = const { RefCell::new(Vec::new()) };
856    static TRADING_CMD_QUEUE: RefCell<Vec<QueuedTradingCommand>> = const { RefCell::new(Vec::new()) };
857    static TRADING_CMD_DISPATCHES: RefCell<Vec<TradingCommandDispatch>> = const { RefCell::new(Vec::new()) };
858}
859
860#[cfg(test)]
861mod tests {
862    use std::{
863        cell::{Cell, RefCell},
864        rc::Rc,
865        sync::Arc,
866    };
867
868    use nautilus_core::{UUID4, UnixNanos};
869    use nautilus_model::identifiers::{AccountId, TraderId};
870    use rstest::rstest;
871    use ustr::Ustr;
872
873    use super::*;
874    use crate::messages::execution::QueryAccount;
875
876    #[derive(Debug)]
877    struct NoopTimeEventSender;
878
879    impl TimeEventSender for NoopTimeEventSender {
880        fn send(&self, _message: TimeEventMessage) {}
881    }
882
883    fn event(name: &str) -> TimeEvent {
884        TimeEvent::new(
885            Ustr::from(name),
886            UUID4::new(),
887            UnixNanos::from(1),
888            UnixNanos::from(2),
889        )
890    }
891
892    fn local_callback(count: Rc<Cell<usize>>) -> TimeEventCallback {
893        TimeEventCallback::RustLocal(Rc::new(move |_| count.set(count.get() + 1)))
894    }
895
896    #[rstest]
897    fn test_time_event_message_is_send_and_sync() {
898        fn assert_send_sync<T: Send + Sync>() {}
899
900        assert_send_sync::<TimeEventMessage>();
901    }
902
903    #[rstest]
904    fn test_trading_command_message_display() {
905        let command = TradingCommand::QueryAccount(QueryAccount::new(
906            TraderId::from("TRADER-001"),
907            None,
908            AccountId::from("SIM-001"),
909            UUID4::from("00000000-0000-4000-8000-000000000001"),
910            UnixNanos::from(1),
911            None,
912            None,
913        ));
914        let message =
915            TradingCommandMessage::new(MessagingSwitchboard::exec_engine_execute(), command);
916
917        assert_eq!(
918            message.to_string(),
919            "TradingCommandMessage(endpoint=ExecEngine.execute, command=QueryAccount(client_id=None, account_id=SIM-001))"
920        );
921    }
922
923    #[rstest]
924    fn test_registered_time_event_dispatches_on_owner_thread() {
925        let count = Rc::new(Cell::new(0));
926        let token = register_time_event_callback(local_callback(count.clone()));
927        let lease = token.acquire().unwrap();
928        let message = TimeEventMessage::registered(event("same-thread"), lease);
929
930        assert!(message.dispatch());
931        assert_eq!(count.get(), 1);
932        assert!(token.is_registered());
933
934        token.close();
935        assert!(!token.is_registered());
936    }
937
938    #[rstest]
939    fn test_registered_time_event_dropped_on_wrong_thread() {
940        let count = Rc::new(Cell::new(0));
941        let token = register_time_event_callback(local_callback(count.clone()));
942        let lease = token.acquire().unwrap();
943        let message = TimeEventMessage::registered(event("wrong-thread"), lease);
944
945        let dispatched = std::thread::spawn(move || message.dispatch())
946            .join()
947            .unwrap();
948
949        assert!(!dispatched);
950        assert_eq!(count.get(), 0);
951        assert!(token.is_registered());
952
953        token.close();
954        assert!(!token.is_registered());
955    }
956
957    #[rstest]
958    fn test_closing_registered_callback_without_leases_removes_it_immediately() {
959        let token = register_time_event_callback(local_callback(Rc::new(Cell::new(0))));
960        assert!(!token.is_closed());
961
962        token.close();
963
964        assert!(token.is_closed());
965        assert!(!token.is_registered());
966    }
967
968    #[rstest]
969    fn test_closing_registered_callback_preserves_queued_leases_until_last_dispatch() {
970        let count = Rc::new(Cell::new(0));
971        let token = register_time_event_callback(local_callback(count.clone()));
972        let first = TimeEventMessage::registered(event("first"), token.acquire().unwrap());
973        let second = TimeEventMessage::registered(event("second"), token.acquire().unwrap());
974
975        token.close();
976        assert!(token.is_registered());
977
978        assert!(first.dispatch());
979        assert_eq!(count.get(), 1);
980        assert!(token.is_registered());
981
982        assert!(second.dispatch());
983        assert_eq!(count.get(), 2);
984        assert!(!token.is_registered());
985    }
986
987    #[rstest]
988    fn test_replaced_registered_callbacks_have_distinct_lifecycles() {
989        let old_count = Rc::new(Cell::new(0));
990        let old = register_time_event_callback(local_callback(old_count.clone()));
991        let old_message = TimeEventMessage::registered(event("same-name"), old.acquire().unwrap());
992        old.close();
993
994        let new_count = Rc::new(Cell::new(0));
995        let new = register_time_event_callback(local_callback(new_count.clone()));
996
997        assert_ne!(old.0.id, new.0.id);
998        assert!(old_message.dispatch());
999        assert_eq!(old_count.get(), 1);
1000        assert_eq!(new_count.get(), 0);
1001        assert!(new.is_registered());
1002
1003        new.close();
1004        assert!(!new.is_registered());
1005    }
1006
1007    #[rstest]
1008    fn test_one_shot_callback_can_rearm_same_name_without_old_lease_removing_new_callback() {
1009        let replacement = Rc::new(RefCell::new(None));
1010        let replacement_slot = replacement.clone();
1011        let callback = TimeEventCallback::RustLocal(Rc::new(move |_| {
1012            let token = register_time_event_callback(TimeEventCallback::RustLocal(Rc::new(|_| {})));
1013            replacement_slot.replace(Some(token));
1014        }));
1015        let old = register_time_event_callback(callback);
1016        let message = TimeEventMessage::registered(event("rearm"), old.acquire().unwrap());
1017        old.close();
1018
1019        assert!(message.dispatch());
1020        assert!(!old.is_registered());
1021
1022        let new = replacement.borrow_mut().take().unwrap();
1023        assert_ne!(old.0.id, new.0.id);
1024        assert!(new.is_registered());
1025        new.close();
1026        assert!(!new.is_registered());
1027    }
1028
1029    #[rstest]
1030    fn test_wrong_thread_final_lease_is_lazily_purged_on_owner_thread() {
1031        let callback: Rc<dyn Fn(TimeEvent)> = Rc::new(|_| {});
1032        let callback_weak = Rc::downgrade(&callback);
1033        let token = register_time_event_callback(TimeEventCallback::RustLocal(callback));
1034        let message = TimeEventMessage::registered(event("lazy-purge"), token.acquire().unwrap());
1035        token.close();
1036        drop(token);
1037
1038        let dispatched = std::thread::spawn(move || message.dispatch())
1039            .join()
1040            .unwrap();
1041
1042        assert!(!dispatched);
1043        assert!(callback_weak.upgrade().is_some());
1044
1045        let next = register_time_event_callback(local_callback(Rc::new(Cell::new(0))));
1046        assert!(callback_weak.upgrade().is_none());
1047        next.close();
1048    }
1049
1050    #[rstest]
1051    #[cfg(any(feature = "live", test))]
1052    fn test_cleanup_message_removes_callback_without_dispatching() {
1053        let count = Rc::new(Cell::new(0));
1054        let token = register_time_event_callback(local_callback(count.clone()));
1055        let cleanup = TimeEventMessage::cleanup(event("cleanup"), token.acquire().unwrap());
1056        token.close();
1057
1058        assert!(!cleanup.dispatch());
1059        assert_eq!(count.get(), 0);
1060        assert!(!token.is_registered());
1061    }
1062
1063    #[rstest]
1064    fn test_purge_retains_closed_entry_while_final_lease_is_queued() {
1065        let count = Rc::new(Cell::new(0));
1066        let token = register_time_event_callback(local_callback(count.clone()));
1067        let message = TimeEventMessage::registered(event("purge-queued"), token.acquire().unwrap());
1068        token.close();
1069
1070        purge_closed_time_event_callbacks();
1071        assert!(token.is_registered());
1072
1073        assert!(message.dispatch());
1074        assert_eq!(count.get(), 1);
1075        assert!(!token.is_registered());
1076    }
1077
1078    #[rstest]
1079    fn test_off_owner_final_lease_drop_is_reclaimed_by_owner_purge() {
1080        let count = Rc::new(Cell::new(0));
1081        let token = register_time_event_callback(local_callback(count.clone()));
1082        let lease = token.acquire().unwrap();
1083        token.close();
1084
1085        std::thread::spawn(move || drop(lease)).join().unwrap();
1086
1087        assert!(token.is_registered());
1088
1089        purge_closed_time_event_callbacks();
1090        assert!(!token.is_registered());
1091        assert_eq!(count.get(), 0);
1092    }
1093
1094    #[rstest]
1095    #[case::token_close(false)]
1096    #[case::final_lease(true)]
1097    fn test_callback_removal_releases_registry_borrow_before_entry_drop(
1098        #[case] via_final_lease: bool,
1099    ) {
1100        let inner = register_time_event_callback(local_callback(Rc::new(Cell::new(0))));
1101        let inner_lease = inner.acquire().unwrap();
1102        inner.close();
1103
1104        // Dropping the outer callback drops this final lease and re-enters the registry
1105        let callback = TimeEventCallback::RustLocal(Rc::new(move |_| {
1106            assert_eq!(inner_lease.0.owner, std::thread::current().id());
1107        }));
1108        let outer = register_time_event_callback(callback);
1109        let outer_lease = via_final_lease.then(|| outer.acquire().unwrap());
1110        outer.close();
1111        drop(outer_lease);
1112
1113        assert!(!outer.is_registered());
1114        assert!(!inner.is_registered());
1115    }
1116
1117    // The two following tests reproduce the destructor-during-TLS-teardown
1118    // abort: a callback holder (a lease, or a token closed from a `Drop` as
1119    // `LiveTimer::drop` does) is placed in a thread-local initialized BEFORE
1120    // `TIME_EVENT_CALLBACKS`. Rust does not guarantee a destruction order
1121    // between independent TLS keys, but the affected implementation (native
1122    // Linux TLS) destroys keys LIFO by initialization order, so the registry
1123    // is torn down first and the holder's own destructor reaches the removal
1124    // path with the registry TLS already gone. On the unfixed `.with` code
1125    // that access panics inside a TLS destructor and aborts the whole process
1126    // (the thread never joins); the `try_with` guard makes it a no-op. This
1127    // mirrors the live path where `MESSAGE_BUS` outlives the callback
1128    // registry and drops the last clock owner during teardown.
1129
1130    #[rstest]
1131    fn test_final_lease_drop_survives_registry_tls_teardown() {
1132        std::thread::spawn(|| {
1133            thread_local! {
1134                static HELD_LEASE: RefCell<Option<TimeEventCallbackLease>> =
1135                    const { RefCell::new(None) };
1136            }
1137
1138            // Initialize the holder before the registry so it is destroyed last.
1139            HELD_LEASE.with(|_| {});
1140
1141            let token = register_time_event_callback(local_callback(Rc::new(Cell::new(0))));
1142            let lease = token.acquire().unwrap();
1143            token.close();
1144            HELD_LEASE.with(|slot| *slot.borrow_mut() = Some(lease));
1145        })
1146        .join()
1147        .expect("final-lease drop after registry teardown must not abort");
1148    }
1149
1150    #[rstest]
1151    fn test_owner_close_survives_registry_tls_teardown() {
1152        struct CloseOnDrop(TimeEventCallbackToken);
1153
1154        impl Drop for CloseOnDrop {
1155            fn drop(&mut self) {
1156                self.0.close();
1157            }
1158        }
1159
1160        std::thread::spawn(|| {
1161            thread_local! {
1162                static HELD_TOKEN: RefCell<Option<CloseOnDrop>> = const { RefCell::new(None) };
1163            }
1164
1165            // Initialize the holder before the registry so it is destroyed last.
1166            HELD_TOKEN.with(|_| {});
1167
1168            let token = register_time_event_callback(local_callback(Rc::new(Cell::new(0))));
1169            HELD_TOKEN.with(|slot| *slot.borrow_mut() = Some(CloseOnDrop(token)));
1170        })
1171        .join()
1172        .expect("owner close after registry teardown must not abort");
1173    }
1174
1175    #[rstest]
1176    fn test_replace_data_cmd_sender_overwrites_previous() {
1177        std::thread::spawn(|| {
1178            replace_data_cmd_sender(Arc::new(SyncDataCommandSender));
1179            replace_data_cmd_sender(Arc::new(SyncDataCommandSender));
1180            let _sender = get_data_cmd_sender();
1181        })
1182        .join()
1183        .unwrap();
1184    }
1185
1186    #[rstest]
1187    fn test_replace_exec_cmd_sender_overwrites_previous() {
1188        std::thread::spawn(|| {
1189            replace_exec_cmd_sender(Arc::new(SyncTradingCommandSender));
1190            replace_exec_cmd_sender(Arc::new(SyncTradingCommandSender));
1191            let _sender = get_trading_cmd_sender();
1192        })
1193        .join()
1194        .unwrap();
1195    }
1196
1197    #[rstest]
1198    fn test_replace_time_event_sender_overwrites_previous() {
1199        std::thread::spawn(|| {
1200            replace_time_event_sender(Arc::new(NoopTimeEventSender));
1201            replace_time_event_sender(Arc::new(NoopTimeEventSender));
1202            let _sender = get_time_event_sender();
1203        })
1204        .join()
1205        .unwrap();
1206    }
1207
1208    #[rstest]
1209    fn test_set_data_cmd_sender_panics_on_double_set() {
1210        let result = std::thread::spawn(|| {
1211            set_data_cmd_sender(Arc::new(SyncDataCommandSender));
1212            set_data_cmd_sender(Arc::new(SyncDataCommandSender));
1213        })
1214        .join();
1215        assert!(result.is_err());
1216    }
1217
1218    #[rstest]
1219    fn test_set_exec_cmd_sender_panics_on_double_set() {
1220        let result = std::thread::spawn(|| {
1221            set_exec_cmd_sender(Arc::new(SyncTradingCommandSender));
1222            set_exec_cmd_sender(Arc::new(SyncTradingCommandSender));
1223        })
1224        .join();
1225        assert!(result.is_err());
1226    }
1227
1228    #[rstest]
1229    fn test_set_time_event_sender_panics_on_double_set() {
1230        let result = std::thread::spawn(|| {
1231            set_time_event_sender(Arc::new(NoopTimeEventSender));
1232            set_time_event_sender(Arc::new(NoopTimeEventSender));
1233        })
1234        .join();
1235        assert!(result.is_err());
1236    }
1237
1238    #[rstest]
1239    fn test_try_get_time_event_sender_returns_none_when_unset() {
1240        let result = std::thread::spawn(try_get_time_event_sender)
1241            .join()
1242            .unwrap();
1243        assert!(result.is_none());
1244    }
1245
1246    #[rstest]
1247    fn test_try_get_trading_cmd_sender_returns_none_when_unset() {
1248        let is_none = std::thread::spawn(|| try_get_trading_cmd_sender().is_none())
1249            .join()
1250            .unwrap();
1251        assert!(is_none);
1252    }
1253}