Skip to main content

nautilus_live/execution/
emitter.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//! Live execution event emitter for async event dispatch.
17//!
18//! This module provides [`ExecutionEventEmitter`], which combines event generation (via
19//! [`OrderEventFactory`]) with async dispatch. Adapters use the `emit_*` convenience
20//! methods to generate and send events in a single call.
21//!
22//! # Architecture
23//!
24//! ```text
25//! Adapter
26//! |-- core: ExecutionClientCore    (identity + connection state)
27//! `-- emitter: ExecutionEventEmitter   (event generation + async dispatch)
28//!     |-- factory: OrderEventFactory
29//!     `-- sender: ArcSwapOption<Sender>   (shared slot, installed at create() and start())
30//! ```
31
32use std::sync::Arc;
33
34use arc_swap::ArcSwapOption;
35use nautilus_common::{
36    factories::OrderEventFactory,
37    live::sender::EventSender,
38    messages::{ExecutionEvent, ExecutionReport},
39};
40use nautilus_core::{Params, UUID4, UnixNanos, time::AtomicTime};
41use nautilus_model::{
42    data::CustomData,
43    enums::{AccountType, LiquiditySide},
44    events::{
45        AccountState, OrderAcceptedBatch, OrderCancelDenied, OrderCancelRejected,
46        OrderCanceledBatch, OrderEventAny, OrderModifyDenied, OrderModifyRejected, OrderRejected,
47        OrderSubmittedBatch,
48    },
49    identifiers::{
50        AccountId, ClientOrderId, InstrumentId, PositionId, StrategyId, TradeId, TraderId,
51        VenueOrderId,
52    },
53    orders::OrderAny,
54    reports::{FillReport, OrderStatusReport, PositionStatusReport},
55    types::{AccountBalance, Currency, MarginBalance, Money, Price, Quantity},
56};
57
58/// Event emitter for live trading - combines event generation with async dispatch.
59///
60/// This struct wraps an [`OrderEventFactory`] for event construction and an unbounded
61/// channel sender for async dispatch. It provides `emit_*` convenience methods that
62/// generate and send events in a single call.
63///
64/// The sender is installed via [`set_sender`](Self::set_sender) in the client's `start`, and in the
65/// execution client factory's `create` when the calling thread has one.
66/// Clones share the sender slot and observe later sender installations and replacements.
67#[derive(Debug, Clone)]
68pub struct ExecutionEventEmitter {
69    clock: &'static AtomicTime,
70    factory: OrderEventFactory,
71    sender: Arc<ArcSwapOption<EventSender<ExecutionEvent>>>,
72}
73
74impl ExecutionEventEmitter {
75    /// Creates a new [`ExecutionEventEmitter`] with no sender.
76    ///
77    /// Call [`set_sender`](Self::set_sender) in the client's `start`, and in the factory's `create`
78    /// when `try_get_exec_event_sender` returns `Some`.
79    #[must_use]
80    pub fn new(
81        clock: &'static AtomicTime,
82        trader_id: TraderId,
83        account_id: AccountId,
84        account_type: AccountType,
85        base_currency: Option<Currency>,
86    ) -> Self {
87        Self {
88            clock,
89            factory: OrderEventFactory::new(trader_id, account_id, account_type, base_currency),
90            sender: Arc::new(ArcSwapOption::empty()),
91        }
92    }
93
94    fn ts_init(&self) -> UnixNanos {
95        self.clock.get_time_ns()
96    }
97
98    /// Installs or replaces the sender for this emitter and all its clones.
99    ///
100    /// The slot is shared, so a clone taken before this call observes the sender it installs.
101    /// Events emitted before any install are dropped with a warning.
102    ///
103    /// Call in the client's `start`, resolved from `get_exec_event_sender`: `LiveNode` rebinds the
104    /// runner's senders on the calling thread before it starts clients, so the `start` install is
105    /// the authoritative one. Call it in the execution client factory's `create` as well when
106    /// `try_get_exec_event_sender` returns `Some`; `None` there means the calling thread has no
107    /// bound senders and is not a construction failure. See the adapter guide for hosts that drive
108    /// a client outside `LiveNode`.
109    pub fn set_sender(&mut self, sender: impl Into<EventSender<ExecutionEvent>>) {
110        self.sender.store(Some(Arc::new(sender.into())));
111    }
112
113    /// Returns true if the sender is initialized for this emitter and its clones.
114    #[must_use]
115    pub fn is_initialized(&self) -> bool {
116        self.sender.load().is_some()
117    }
118
119    /// Returns the trader ID.
120    #[must_use]
121    pub fn trader_id(&self) -> TraderId {
122        self.factory.trader_id()
123    }
124
125    /// Returns the account ID.
126    #[must_use]
127    pub fn account_id(&self) -> AccountId {
128        self.factory.account_id()
129    }
130
131    /// Sets the account ID for generated events.
132    pub fn set_account_id(&mut self, account_id: AccountId) {
133        self.factory.set_account_id(account_id);
134    }
135
136    /// Generates and emits an account state event.
137    pub fn emit_account_state(
138        &self,
139        balances: Vec<AccountBalance>,
140        margins: Vec<MarginBalance>,
141        reported: bool,
142        ts_event: UnixNanos,
143        info: Option<Params>,
144    ) {
145        if let Err(e) = self.try_emit_account_state(balances, margins, reported, ts_event, info) {
146            log::warn!("{e}");
147        }
148    }
149
150    /// Generates and emits an account state event, reporting dispatch failures.
151    ///
152    /// # Errors
153    ///
154    /// Returns an error if the sender is uninitialized or its receiver is closed.
155    pub fn try_emit_account_state(
156        &self,
157        balances: Vec<AccountBalance>,
158        margins: Vec<MarginBalance>,
159        reported: bool,
160        ts_event: UnixNanos,
161        info: Option<Params>,
162    ) -> anyhow::Result<()> {
163        let state = self.factory.generate_account_state(
164            balances,
165            margins,
166            reported,
167            ts_event,
168            self.ts_init(),
169            info,
170        );
171        self.try_send_account_state(state)
172    }
173
174    /// Generates and emits an order denied event.
175    pub fn emit_order_denied(&self, order: &OrderAny, reason: &str) {
176        let event = self
177            .factory
178            .generate_order_denied(order, reason, self.ts_init());
179        self.send_order_event(event);
180    }
181
182    /// Generates and emits an order submitted event.
183    pub fn emit_order_submitted(&self, order: &OrderAny) {
184        if let Err(e) = self.try_emit_order_submitted(order) {
185            log::warn!("{e}");
186        }
187    }
188
189    /// Generates and emits an order submitted event, reporting dispatch failures.
190    ///
191    /// # Errors
192    ///
193    /// Returns an error if the sender is uninitialized or its receiver is closed.
194    pub fn try_emit_order_submitted(&self, order: &OrderAny) -> anyhow::Result<()> {
195        let event = self.factory.generate_order_submitted(order, self.ts_init());
196        self.try_send_order_event(event)
197    }
198
199    /// Generates and emits an order rejected event.
200    pub fn emit_order_rejected(
201        &self,
202        order: &OrderAny,
203        reason: &str,
204        ts_event: UnixNanos,
205        due_post_only: bool,
206    ) {
207        let event = self.factory.generate_order_rejected(
208            order,
209            reason,
210            ts_event,
211            self.ts_init(),
212            due_post_only,
213        );
214        self.send_order_event(event);
215    }
216
217    /// Generates and emits an order accepted event.
218    pub fn emit_order_accepted(
219        &self,
220        order: &OrderAny,
221        venue_order_id: VenueOrderId,
222        ts_event: UnixNanos,
223    ) {
224        let event =
225            self.factory
226                .generate_order_accepted(order, venue_order_id, ts_event, self.ts_init());
227        self.send_order_event(event);
228    }
229
230    /// Generates and emits an order modify denied event.
231    pub fn emit_order_modify_denied(
232        &self,
233        order: &OrderAny,
234        reason: &str,
235        ts_event: UnixNanos,
236        causation_id: Option<UUID4>,
237    ) {
238        let event = self.factory.generate_order_modify_denied(
239            order,
240            reason,
241            causation_id,
242            ts_event,
243            self.ts_init(),
244        );
245        self.send_order_event(event);
246    }
247
248    /// Generates and emits an order modify rejected event.
249    pub fn emit_order_modify_rejected(
250        &self,
251        order: &OrderAny,
252        venue_order_id: Option<VenueOrderId>,
253        reason: &str,
254        ts_event: UnixNanos,
255        causation_id: Option<UUID4>,
256    ) {
257        let event = self.factory.generate_order_modify_rejected(
258            order,
259            venue_order_id,
260            reason,
261            ts_event,
262            self.ts_init(),
263            causation_id,
264        );
265        self.send_order_event(event);
266    }
267
268    /// Generates and emits an order cancel denied event.
269    pub fn emit_order_cancel_denied(
270        &self,
271        order: &OrderAny,
272        reason: &str,
273        ts_event: UnixNanos,
274        causation_id: Option<UUID4>,
275    ) {
276        let event = self.factory.generate_order_cancel_denied(
277            order,
278            reason,
279            causation_id,
280            ts_event,
281            self.ts_init(),
282        );
283        self.send_order_event(event);
284    }
285
286    /// Generates and emits an order cancel rejected event.
287    pub fn emit_order_cancel_rejected(
288        &self,
289        order: &OrderAny,
290        venue_order_id: Option<VenueOrderId>,
291        reason: &str,
292        ts_event: UnixNanos,
293        causation_id: Option<UUID4>,
294    ) {
295        let event = self.factory.generate_order_cancel_rejected(
296            order,
297            venue_order_id,
298            reason,
299            ts_event,
300            self.ts_init(),
301            causation_id,
302        );
303        self.send_order_event(event);
304    }
305
306    /// Generates and emits an order updated event.
307    #[expect(clippy::too_many_arguments)]
308    pub fn emit_order_updated(
309        &self,
310        order: &OrderAny,
311        venue_order_id: VenueOrderId,
312        quantity: Quantity,
313        price: Option<Price>,
314        trigger_price: Option<Price>,
315        protection_price: Option<Price>,
316        ts_event: UnixNanos,
317    ) {
318        let event = self.factory.generate_order_updated(
319            order,
320            venue_order_id,
321            quantity,
322            price,
323            trigger_price,
324            protection_price,
325            ts_event,
326            self.ts_init(),
327        );
328        self.send_order_event(event);
329    }
330
331    /// Generates and emits an order canceled event.
332    pub fn emit_order_canceled(
333        &self,
334        order: &OrderAny,
335        venue_order_id: Option<VenueOrderId>,
336        ts_event: UnixNanos,
337    ) {
338        let event =
339            self.factory
340                .generate_order_canceled(order, venue_order_id, ts_event, self.ts_init());
341        self.send_order_event(event);
342    }
343
344    /// Generates and emits an order triggered event.
345    pub fn emit_order_triggered(
346        &self,
347        order: &OrderAny,
348        venue_order_id: Option<VenueOrderId>,
349        ts_event: UnixNanos,
350    ) {
351        let event =
352            self.factory
353                .generate_order_triggered(order, venue_order_id, ts_event, self.ts_init());
354        self.send_order_event(event);
355    }
356
357    /// Generates and emits an order expired event.
358    pub fn emit_order_expired(
359        &self,
360        order: &OrderAny,
361        venue_order_id: Option<VenueOrderId>,
362        ts_event: UnixNanos,
363    ) {
364        let event =
365            self.factory
366                .generate_order_expired(order, venue_order_id, ts_event, self.ts_init());
367        self.send_order_event(event);
368    }
369
370    /// Generates and emits an order filled event.
371    #[expect(clippy::too_many_arguments)]
372    pub fn emit_order_filled(
373        &self,
374        order: &OrderAny,
375        venue_order_id: VenueOrderId,
376        venue_position_id: Option<PositionId>,
377        trade_id: TradeId,
378        last_qty: Quantity,
379        last_px: Price,
380        quote_currency: Currency,
381        commission: Option<Money>,
382        liquidity_side: LiquiditySide,
383        ts_event: UnixNanos,
384    ) {
385        let event = self.factory.generate_order_filled(
386            order,
387            venue_order_id,
388            venue_position_id,
389            trade_id,
390            last_qty,
391            last_px,
392            quote_currency,
393            commission,
394            liquidity_side,
395            ts_event,
396            self.ts_init(),
397        );
398        self.send_order_event(event);
399    }
400
401    /// Constructs and emits an order rejected event from raw fields.
402    pub fn emit_order_rejected_event(
403        &self,
404        strategy_id: StrategyId,
405        instrument_id: InstrumentId,
406        client_order_id: ClientOrderId,
407        reason: &str,
408        ts_event: UnixNanos,
409        due_post_only: bool,
410    ) {
411        let event = OrderRejected::new(
412            self.factory.trader_id(),
413            strategy_id,
414            instrument_id,
415            client_order_id,
416            self.factory.account_id(),
417            reason.into(),
418            UUID4::new(),
419            ts_event,
420            self.ts_init(),
421            false,
422            due_post_only,
423        );
424        self.send_order_event(OrderEventAny::Rejected(event));
425    }
426
427    /// Constructs and emits an order modify denied event from raw fields.
428    #[expect(
429        clippy::too_many_arguments,
430        reason = "Event emission preserves order identity and command correlation"
431    )]
432    pub fn emit_order_modify_denied_event(
433        &self,
434        strategy_id: StrategyId,
435        instrument_id: InstrumentId,
436        client_order_id: ClientOrderId,
437        venue_order_id: Option<VenueOrderId>,
438        reason: &str,
439        ts_event: UnixNanos,
440        causation_id: Option<UUID4>,
441    ) {
442        let mut event = OrderModifyDenied::new(
443            self.factory.trader_id(),
444            strategy_id,
445            instrument_id,
446            client_order_id,
447            reason.into(),
448            UUID4::new(),
449            ts_event,
450            self.ts_init(),
451            venue_order_id,
452            Some(self.factory.account_id()),
453        );
454        event.causation_id = causation_id;
455        self.send_order_event(OrderEventAny::ModifyDenied(event));
456    }
457
458    /// Constructs and emits an order modify rejected event from raw fields.
459    #[expect(
460        clippy::too_many_arguments,
461        reason = "Event emission preserves order identity and command correlation"
462    )]
463    pub fn emit_order_modify_rejected_event(
464        &self,
465        strategy_id: StrategyId,
466        instrument_id: InstrumentId,
467        client_order_id: ClientOrderId,
468        venue_order_id: Option<VenueOrderId>,
469        reason: &str,
470        ts_event: UnixNanos,
471        causation_id: Option<UUID4>,
472    ) {
473        let mut event = OrderModifyRejected::new(
474            self.factory.trader_id(),
475            strategy_id,
476            instrument_id,
477            client_order_id,
478            reason.into(),
479            UUID4::new(),
480            ts_event,
481            self.ts_init(),
482            false,
483            venue_order_id,
484            Some(self.factory.account_id()),
485        );
486        event.causation_id = causation_id;
487        self.send_order_event(OrderEventAny::ModifyRejected(event));
488    }
489
490    /// Constructs and emits an order cancel denied event from raw fields.
491    #[expect(
492        clippy::too_many_arguments,
493        reason = "Event emission preserves order identity and command correlation"
494    )]
495    pub fn emit_order_cancel_denied_event(
496        &self,
497        strategy_id: StrategyId,
498        instrument_id: InstrumentId,
499        client_order_id: ClientOrderId,
500        venue_order_id: Option<VenueOrderId>,
501        reason: &str,
502        ts_event: UnixNanos,
503        causation_id: Option<UUID4>,
504    ) {
505        let mut event = OrderCancelDenied::new(
506            self.factory.trader_id(),
507            strategy_id,
508            instrument_id,
509            client_order_id,
510            reason.into(),
511            UUID4::new(),
512            ts_event,
513            self.ts_init(),
514            venue_order_id,
515            Some(self.factory.account_id()),
516        );
517        event.causation_id = causation_id;
518        self.send_order_event(OrderEventAny::CancelDenied(event));
519    }
520
521    /// Constructs and emits an order cancel rejected event from raw fields.
522    #[expect(
523        clippy::too_many_arguments,
524        reason = "Event emission preserves order identity and command correlation"
525    )]
526    pub fn emit_order_cancel_rejected_event(
527        &self,
528        strategy_id: StrategyId,
529        instrument_id: InstrumentId,
530        client_order_id: ClientOrderId,
531        venue_order_id: Option<VenueOrderId>,
532        reason: &str,
533        ts_event: UnixNanos,
534        causation_id: Option<UUID4>,
535    ) {
536        let mut event = OrderCancelRejected::new(
537            self.factory.trader_id(),
538            strategy_id,
539            instrument_id,
540            client_order_id,
541            reason.into(),
542            UUID4::new(),
543            ts_event,
544            self.ts_init(),
545            false,
546            venue_order_id,
547            Some(self.factory.account_id()),
548        );
549        event.causation_id = causation_id;
550        self.send_order_event(OrderEventAny::CancelRejected(event));
551    }
552
553    /// Emits an order event.
554    pub fn send_order_event(&self, event: OrderEventAny) {
555        if let Err(e) = self.try_send_order_event(event) {
556            log::warn!("{e}");
557        }
558    }
559
560    /// Emits an order event and returns any channel error to the caller.
561    ///
562    /// # Errors
563    ///
564    /// Returns an error if the sender is uninitialized or its receiver is closed.
565    pub fn try_send_order_event(&self, event: OrderEventAny) -> anyhow::Result<()> {
566        self.try_send(ExecutionEvent::Order(event), "order event")
567    }
568
569    /// Emits a batch of order submitted events as a single channel message.
570    pub fn send_order_submitted_batch(&self, batch: OrderSubmittedBatch) {
571        if let Err(e) = self.try_send(
572            ExecutionEvent::OrderSubmittedBatch(batch),
573            "order submitted batch",
574        ) {
575            log::warn!("{e}");
576        }
577    }
578
579    /// Emits a batch of order accepted events as a single channel message.
580    pub fn send_order_accepted_batch(&self, batch: OrderAcceptedBatch) {
581        if let Err(e) = self.try_send(
582            ExecutionEvent::OrderAcceptedBatch(batch),
583            "order accepted batch",
584        ) {
585            log::warn!("{e}");
586        }
587    }
588
589    /// Emits a batch of order canceled events as a single channel message.
590    pub fn send_order_canceled_batch(&self, batch: OrderCanceledBatch) {
591        if let Err(e) = self.try_send(
592            ExecutionEvent::OrderCanceledBatch(batch),
593            "order canceled batch",
594        ) {
595            log::warn!("{e}");
596        }
597    }
598
599    /// Emits an account state event.
600    pub fn send_account_state(&self, state: AccountState) {
601        if let Err(e) = self.try_send_account_state(state) {
602            log::warn!("{e}");
603        }
604    }
605
606    /// Emits custom data for publication on the message bus.
607    pub fn send_custom_data(&self, data: CustomData) {
608        if let Err(e) = self.try_send(ExecutionEvent::Data(data), "custom data") {
609            log::warn!("{e}");
610        }
611    }
612
613    /// Emits an account state event and returns any channel error to the caller.
614    ///
615    /// # Errors
616    ///
617    /// Returns an error if the sender is uninitialized or its receiver is closed.
618    pub fn try_send_account_state(&self, state: AccountState) -> anyhow::Result<()> {
619        self.try_send(ExecutionEvent::Account(state), "account state")
620    }
621
622    /// Emits an execution report.
623    pub fn send_execution_report(&self, report: ExecutionReport) {
624        if let Err(e) = self.try_send_execution_report(report) {
625            log::warn!("{e}");
626        }
627    }
628
629    /// Emits an execution report and returns any channel error to the caller.
630    ///
631    /// # Errors
632    ///
633    /// Returns an error if the sender is not initialized or the receiving channel is closed.
634    pub fn try_send_execution_report(&self, report: ExecutionReport) -> anyhow::Result<()> {
635        self.try_send(ExecutionEvent::Report(report), "execution report")
636    }
637
638    /// Emits an order status report.
639    pub fn send_order_status_report(&self, report: OrderStatusReport) {
640        self.send_execution_report(ExecutionReport::Order(Box::new(report)));
641    }
642
643    /// Emits a fill report.
644    pub fn send_fill_report(&self, report: FillReport) {
645        self.send_execution_report(ExecutionReport::Fill(Box::new(report)));
646    }
647
648    /// Emits an order status report bundled with the fills that produced it.
649    pub fn send_order_with_fills(&self, report: OrderStatusReport, fills: Vec<FillReport>) {
650        self.send_execution_report(ExecutionReport::OrderWithFills(Box::new(report), fills));
651    }
652
653    /// Emits a position status report.
654    pub fn send_position_report(&self, report: PositionStatusReport) {
655        self.send_execution_report(ExecutionReport::Position(Box::new(report)));
656    }
657
658    fn try_send(&self, event: ExecutionEvent, kind: &str) -> anyhow::Result<()> {
659        let sender = self.sender.load();
660        let sender = sender
661            .as_ref()
662            .ok_or_else(|| anyhow::anyhow!("Cannot send {kind}: sender not initialized"))?;
663        sender
664            .send(event)
665            .map_err(|e| anyhow::anyhow!("Failed to send {kind}: {e}"))
666    }
667}
668
669#[cfg(test)]
670mod tests {
671    use nautilus_core::time::get_atomic_clock_static;
672    use nautilus_model::events::order::spec::OrderSubmittedSpec;
673    use rstest::rstest;
674
675    use super::*;
676
677    fn create_emitter() -> ExecutionEventEmitter {
678        ExecutionEventEmitter::new(
679            get_atomic_clock_static(),
680            TraderId::from("TRADER-001"),
681            AccountId::from("SIM-001"),
682            AccountType::Cash,
683            None,
684        )
685    }
686
687    fn create_order_event() -> OrderEventAny {
688        OrderEventAny::Submitted(
689            OrderSubmittedSpec::builder()
690                .client_order_id(ClientOrderId::from("O-001"))
691                .build(),
692        )
693    }
694
695    #[rstest]
696    fn test_clone_before_set_sender_observes_sender() {
697        let mut emitter = create_emitter();
698        let cloned = emitter.clone();
699        let (tx, mut rx) = tokio::sync::mpsc::unbounded_channel();
700
701        emitter.set_sender(tx);
702
703        assert!(cloned.is_initialized());
704        cloned.send_order_event(create_order_event());
705        assert!(matches!(
706            rx.try_recv(),
707            Ok(ExecutionEvent::Order(OrderEventAny::Submitted(_)))
708        ));
709    }
710
711    #[rstest]
712    fn test_set_sender_replaces_existing_sender() {
713        let mut emitter = create_emitter();
714        let (tx_a, mut rx_a) = tokio::sync::mpsc::unbounded_channel();
715        let (tx_b, mut rx_b) = tokio::sync::mpsc::unbounded_channel();
716
717        emitter.set_sender(tx_a);
718        emitter.set_sender(tx_b);
719        emitter.send_order_event(create_order_event());
720
721        assert!(matches!(
722            rx_a.try_recv(),
723            Err(tokio::sync::mpsc::error::TryRecvError::Disconnected)
724        ));
725        assert!(matches!(
726            rx_b.try_recv(),
727            Ok(ExecutionEvent::Order(OrderEventAny::Submitted(_)))
728        ));
729    }
730
731    #[rstest]
732    fn test_never_initialized_sender_drops_or_errors() {
733        let emitter = create_emitter();
734
735        emitter.send_order_event(create_order_event());
736        let error = emitter
737            .try_send_order_event(create_order_event())
738            .unwrap_err();
739
740        assert_eq!(
741            error.to_string(),
742            "Cannot send order event: sender not initialized"
743        );
744    }
745}