v1.5.0: capture event timestamp once per order (+~30% throughput); architecture diagram

Author: Leotaby

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## v1.5.0 (2026-05-30)
+
+### Performance
+- **Capture the event timestamp once per order instead of once per fill.** Both
+  `OrderBook` and `ArrayOrderBook` were calling `steady_clock::now()` (~17 ns)
+  for the order's entry plus every trade print and both sides of every fill —
+  ~4 clock reads per order, which profiling put at ~40% of hot-path time. The
+  engine now reads the clock once per inbound event and threads it through
+  matching via `Order::fill(qty, ts)` / `Order::cancel(ts)`. Measured on x86
+  (1M orders): `std::map` 5.9M→7.6M orders/sec (**+28%**), `ArrayOrderBook`
+  6.7M→8.8M (**+30%**). Trade streams are unchanged — the `orderbook_equivalence`
+  and `gateway_e2e` CI gates still pass.
+
+### Docs
+- README architecture diagram now shows the TCP gateway and the two book
+  backends feeding the matching engine.
+
 ## v1.4.0 (2026-05-30)
 
 ### New features

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.20)
 project(MicroExchange
-    VERSION 1.4.0
+    VERSION 1.5.0
     LANGUAGES CXX
     DESCRIPTION "Exchange-grade CLOB matching engine + microstructure analytics"
 )

README.md

@@ -33,28 +33,24 @@ A complete market microstructure laboratory: from order entry to trade print, fr
 ## Architecture
 
 ```
-┌──────────────────────────────────────────────────────────────────────┐
-│                        MicroExchange Architecture                    │
-│                                                                      │
-│  ┌──────────────┐    ┌──────────────────┐     ┌──────────────────┐   │
-│  │  Simulation  │───▶│  Matching Engine │───▶│  Market Data Feed │   │
-│  │  (Hawkes /   │    │  (CLOB + FIFO)   │    │  (ITCH-style)     │   │
-│  │   ZI agents) │    │                  │    │                   │   │
-│  └──────────────┘    │  • Limit/Market  │    │  • Incremental    │   │
-│                      │  • IOC / FOK     │    │  • Snapshots      │   │
-│  ┌──────────────┐    │  • Stop/StopLim  │    │  • Trade prints   │   │
-│  │  ITCH Replay │───▶│  • Amend/Cancel  │    └────────┬──────────┘   │
-│  │  (historical │    │  • Partial fills │             │              │
-│  │   data)      │    └──────────────────┘             ▼              │
-│  └──────────────┘                              ┌────────────────────┐│
-│                                                │    Analytics       ││
-│                                                │  • Spread decomp   ││
-│                                                │  • Price impact    ││
-│                                                │  • Kyle's λ        ││
-│                                                │  • Order imbalance ││
-│                                                │  • Stylized facts  ││
-│                                                └────────────────────┘│
-└──────────────────────────────────────────────────────────────────────┘
+  order sources                  matching core                      outputs
+  ─────────────                  ─────────────                      ───────
+
+  ┌──────────────┐
+  │ TCP Gateway  │─┐   binary order-entry protocol over a socket (net/)
+  └──────────────┘ │
+  ┌──────────────┐ │   ┌────────────────────────────┐    ┌──────────────────┐
+  │ Simulation   │ ├──▶│      Matching Engine        │──▶ │ Market Data Feed │
+  │ (Hawkes/ZI)  │ │   │ price-time priority (FIFO)  │    │ (ITCH-style:     │
+  └──────────────┘ │   │ Limit/Market/IOC/FOK/Stop   │    │ incremental +    │
+  ┌──────────────┐ │   │                             │    │ snapshots)       │
+  │ ITCH Replay  │─┘   │ book backends (same API):   │    └──────────────────┘
+  │ (historical) │     │  • OrderBook     (std::map) │    ┌──────────────────┐
+  └──────────────┘     │  • ArrayOrderBook (array +  │──▶ │ Analytics        │
+                       │     bitmap BBO index)       │    │ spread decomp,   │
+                       └────────────────────────────┘    │ Kyle's λ, OFI,   │
+                                                          │ stylized facts   │
+                                                          └──────────────────┘
 ```
 
 ---
@@ -241,7 +237,10 @@ Two takeaways that matter more than a single headline number:
    is ~even but median latency drops ~33% (84 ns vs 125 ns). Either way the
    array is competitive-or-faster — and the ceiling is set by the per-order
    `OrderId→Order*` hash insert and the `now()` timestamp, *not* the level
-   container, so trimming `now()` off the hot path is the next optimization.
+   container. **v1.5.0 acts on exactly this:** capturing the timestamp once per
+   order instead of once per fill raised both books ~28–30% on x86 (`std::map`
+   5.9M→7.6M/s, array 6.7M→8.8M/s); the `OrderId` hash insert is now the
+   dominant remaining per-order cost.
 2. **A flat array needs an index.** A naive linear best-bid/ask scan is ~25×
    *slower* than `std::map` on a wide/sparse book because it walks empty levels;
    the bitmap occupied-index fixes that and keeps the array ≥1.0× through

core/include/ArrayOrderBook.h

@@ -86,6 +86,7 @@ class ArrayOrderBook {
     // ═══════════════════════════════════════════
 
     Order* add_order(const NewOrderRequest& req) {
+        ts_ = now();                 // one clock read per event; reused for every fill
         Order* order = order_arena_.allocate();
         new (order) Order{};
 
@@ -99,16 +100,16 @@ class ArrayOrderBook {
         order->quantity   = req.quantity;
         order->leaves_qty = req.quantity;
         order->filled_qty = 0;
-        order->entry_time = now();
-        order->last_update = order->entry_time;
+        order->entry_time = ts_;
+        order->last_update = ts_;
         order->status     = OrderStatus::New;
         std::memcpy(order->symbol, req.symbol, sizeof(order->symbol));
 
         order_index_[order->id] = order;
 
         // FOK: only execute if the whole quantity can be filled right now.
         if (order->type == OrderType::FOK && !can_fill_completely(order)) {
-            order->cancel();
+            order->cancel(ts_);
             order_index_.erase(order->id);
             notify_order(*order);
             return order;
@@ -121,7 +122,7 @@ class ArrayOrderBook {
                 rest_order(order);
             } else {
                 // Market / IOC / FOK remainder, or out-of-band limit, cancels.
-                order->cancel();
+                order->cancel(ts_);
                 order_index_.erase(order->id);
                 notify_order(*order);
             }
@@ -280,7 +281,7 @@ class ArrayOrderBook {
             trade.sequence  = next_sequence_++;
             trade.price     = resting->price;   // price improvement to the resting side
             trade.quantity  = fill_qty;
-            trade.exec_time = now();
+            trade.exec_time = ts_;
             trade.aggressor = incoming->side;
             std::memcpy(trade.symbol, incoming->symbol, sizeof(trade.symbol));
 
@@ -293,8 +294,8 @@ class ArrayOrderBook {
             }
 
             level.reduce_quantity(fill_qty);
-            incoming->fill(fill_qty);
-            resting->fill(fill_qty);
+            incoming->fill(fill_qty, ts_);
+            resting->fill(fill_qty, ts_);
 
             notify_trade(trade);
             notify_order(*resting);
@@ -378,6 +379,8 @@ class ArrayOrderBook {
     std::unordered_map<OrderId, Order*> order_index_;
     ArenaAllocator<Order>               order_arena_;
 
+    Timestamp ts_{};   // wall-clock captured once per inbound event (hot path)
+
     SeqNum   next_sequence_     = 1;
     uint64_t trade_count_       = 0;
     uint64_t total_volume_      = 0;

core/include/Order.h

@@ -117,18 +117,23 @@ struct alignas(64) Order {
         return status == OrderStatus::New || status == OrderStatus::PartiallyFilled;
     }
 
-    void fill(Quantity qty) noexcept {
+    // Hot-path variants take a caller-supplied timestamp. The matching engine
+    // captures now() once per inbound event and threads it through every fill,
+    // rather than re-reading the clock (~17ns) several times per order.
+    void fill(Quantity qty, Timestamp ts) noexcept {
         filled_qty += qty;
         leaves_qty -= qty;
-        last_update = now();
+        last_update = ts;
         status = (leaves_qty == 0) ? OrderStatus::Filled : OrderStatus::PartiallyFilled;
     }
+    void fill(Quantity qty) noexcept { fill(qty, now()); }
 
-    void cancel() noexcept {
+    void cancel(Timestamp ts) noexcept {
         status = OrderStatus::Cancelled;
         leaves_qty = 0;
-        last_update = now();
+        last_update = ts;
     }
+    void cancel() noexcept { cancel(now()); }
 };
 
 // ─────────────────────────────────────────────

core/include/OrderBook.h

@@ -92,6 +92,7 @@ class OrderBook {
      */
     Order* add_order(const NewOrderRequest& req) {
         // Allocate from arena (zero malloc)
+        ts_ = now();                 // one clock read per event; reused for every fill
         Order* order = order_arena_.allocate();
         new (order) Order{};
 
@@ -105,8 +106,8 @@ class OrderBook {
         order->quantity  = req.quantity;
         order->leaves_qty = req.quantity;
         order->filled_qty = 0;
-        order->entry_time = now();
-        order->last_update = order->entry_time;
+        order->entry_time = ts_;
+        order->last_update = ts_;
         order->status    = OrderStatus::New;
         std::memcpy(order->symbol, req.symbol, sizeof(order->symbol));
 
@@ -136,14 +137,14 @@ class OrderBook {
                 case OrderType::Market:
                 case OrderType::IOC:
                     // Cancel unfilled remainder
-                    order->cancel();
+                    order->cancel(ts_);
                     order_index_.erase(order->id);
                     notify_order(*order);
                     break;
                 case OrderType::FOK:
                     // Should have been fully filled or not at all
                     // (FOK pre-check happens in match())
-                    order->cancel();
+                    order->cancel(ts_);
                     order_index_.erase(order->id);
                     notify_order(*order);
                     break;
@@ -201,6 +202,7 @@ class OrderBook {
         Order* order = it->second;
         if (!order->is_active()) return false;
 
+        ts_ = now();
         bool price_changed = (req.new_price != 0 && req.new_price != order->price);
         bool qty_increased = (req.new_quantity != 0 && req.new_quantity > order->leaves_qty);
 
@@ -215,7 +217,7 @@ class OrderBook {
             }
             order->sequence = next_sequence_++;
             order->status = OrderStatus::Amended;
-            order->last_update = now();
+            order->last_update = ts_;
 
             // Re-match then rest
             match(order);
@@ -228,7 +230,7 @@ class OrderBook {
             order->leaves_qty = req.new_quantity;
             order->quantity -= reduction;
             order->status = OrderStatus::Amended;
-            order->last_update = now();
+            order->last_update = ts_;
 
             // Update level aggregate
             auto& levels = order->is_buy() ? bids_ : asks_;
@@ -405,7 +407,7 @@ class OrderBook {
                 trade.sequence = next_sequence_++;
                 trade.price = resting->price;  // Resting order's price (price improvement)
                 trade.quantity = fill_qty;
-                trade.exec_time = now();
+                trade.exec_time = ts_;
                 trade.aggressor = incoming->side;
                 std::memcpy(trade.symbol, incoming->symbol, sizeof(trade.symbol));
 
@@ -422,8 +424,8 @@ class OrderBook {
                 // because fill() modifies the order in-place and the level still references it.
                 // Learned this the hard way (assertion failures in PriceLevel::reduce_quantity).
                 level.reduce_quantity(fill_qty);
-                incoming->fill(fill_qty);
-                resting->fill(fill_qty);
+                incoming->fill(fill_qty, ts_);
+                resting->fill(fill_qty, ts_);
 
                 // Notify
                 notify_trade(trade);
@@ -536,7 +538,7 @@ class OrderBook {
                     o->tif  = TimeInForce::GTC;
                 }
                 o->sequence    = next_sequence_++;
-                o->last_update = now();
+                o->last_update = ts_;
                 ++stop_triggered_count_;
 
                 match(o);
@@ -545,7 +547,7 @@ class OrderBook {
                     if (o->type == OrderType::Limit) {
                         rest_order(o);
                     } else {
-                        o->cancel();
+                        o->cancel(ts_);
                         order_index_.erase(o->id);
                         notify_order(*o);
                     }
@@ -605,6 +607,8 @@ class OrderBook {
     std::unordered_map<OrderId, Order*> order_index_;
     ArenaAllocator<Order>               order_arena_;
 
+    Timestamp ts_{};   // wall-clock captured once per inbound event (hot path)
+
     SeqNum   next_sequence_ = 1;
     uint64_t trade_count_   = 0;
     uint64_t total_volume_  = 0;