{"repo":"PIYUSH-KUMAR1809/order-matching-engine","free":true,"listed":false,"github":"https://github.com/PIYUSH-KUMAR1809/order-matching-engine","clone":"git clone https://github.com/PIYUSH-KUMAR1809/order-matching-engine.git","description":"High performance order matching engine","language":"C++","stars":158,"topics":["cplusplus","cplusplus-20","cpp","cpp20","finance","hft","high-performance","lock-free","low-latency","matching-engine","order-matching-engine"],"license":"MIT","category":"hft_engine","readme_excerpt":"# High-Performance Order Matching Engine\n\nA production-grade, high-frequency trading (HFT) Limit Order Book (LOB) and Matching Engine written in C++20. Designed for extreme throughput, deterministic latency, and cache efficiency using modern lock-free techniques.\n\n  [](https://github.com/PIYUSH-KUMAR1809/order-matching-engine/actions/workflows/cmake.yml) [](https://github.com/wilsonfreitas/awesome-quant)\n\n> **Performance Benchmark**: **~160,000,000 orders/second** (Average) | **~171,000,000** (Peak) on Apple M1 Pro.\n\n### โก๏ธ Key Takeaways\n* **Architecture**: Sharded \"Share-by-Communicating\" design avoids global locks.\n* **Memory**: `std::pmr` monotonic buffers on the stack = 0 heap allocations on hot path.\n* **Optimization**: `alignas(128)` (vs 64) reduced M1/M2 false sharing by ~5%.\n* **Latency**: Sub-microsecond matching latency within the engine core.\n\n---\n\n## ๐ Key Features\n\n* **Ultra-High Throughput**: Capable of processing **>160 million** distinct order operations per second on a single machine.\n* **Zero-Allocation Hot Path**:\n * **PMR (Polymorphic Memory Resources)**: Uses `std::pmr::monotonic_buffer_resource` with a pre-allocated 512MB stack buffer for nanosecond-level allocations.\n * **Soft Limits**: Gracefully falls back to heap allocation if the static buffer is exhausted (no crashes).\n* **Lock-Free Architecture**:\n * **SPSC Ring Buffer**: Custom cache-line aligned (`alignas(128)`) ring buffer for thread-safe, lock-free communication between producer and consumer.\n * **Shard-per-Core**: \"Share by Communicating\" design. Each CPU core owns a dedicated shard, eliminating mutex contention entirely.\n * **Thread Pinning**: Experimentally verified `pthread_setaffinity_np` / `thread_policy_set` guarantees exclusive core usage for worker threads.\n* **Cache Optimizations**:\n * **Flat OrderBook**: Replaces node-based maps with `std::vector` for linear memory access.\n * **Bitset Scanning**: Uses CPU intrinsics (`__builtin_ctzll`) to \"teleport\" to the next active price level, skipping empty levels instantly. Optimized to avoid \"ghost level\" checks.\n * **Compact Storage**: Order objects are PODs (Plain Old Data) optimized for `memcpy`.\n* **Smart Batching**:\n * **Producer-Side**: Thread-local accumulation of orders reduces atomic contention on the RingBuffer tail.\n * **Consumer-Side**: Workers pop commands in batches (up to 256) to amortize cache line invalidations.\n* **Verification & Safety**:\n * **Deterministic**: `--verify` mode runs a mathematically verifiable sequence (Matches == Min(Buys, Sells)).\n * **Instrumentation**: `--latency` mode enables wall-clock end-to-end latency tracking.\n\n---\n\n## ๐ Architecture\n\nThe system moves away from the traditional \"Central Limit Order Book with Global Lock\" to a **Partitioned/Sharded Model**.\n\n```mermaid\ngraph LR\n %% Styles for high visibility and contrast\n classDef client fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,color:#0d47a1\n classDef infra fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c\n classDef core fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20\n classDef memory fill:#fff3e0,stroke:#e65100,stroke-width:2px,color:#e65100\n\n User([User / Network]) -->|TCP Input| Gateway{Symbol Mapping}\n class User client\n class Gateway infra\n\n %% Shard 0 Pipeline\n subgraph Core0 [Core 0: Pinned]\n direction TB\n RB0[Ring Buffer
SPSC Lock-Free]:::infra\n Matcher0[Matching Engine
Shard 0]:::core\n Mem0[PMR Arena
Stack Buffer]:::memory\n \n RB0 --> Matcher0\n Matcher0 --> Mem0\n end\n\n %% Shard 1 Pipeline\n subgraph Core1 [Core 1: Pinned]\n direction TB\n RB1[Ring Buffer
SPSC Lock-Free]:::infra\n Matcher1[Matching Engine
Shard 1]:::core\n Mem1[PMR Arena
Stack Buffer]:::memory\n \n RB1 --> Matcher1\n Matcher1 --> Mem1\n end\n\n %% Routing (No crossing)\n Gateway -->|Shard 0: GOOG, MSFT| RB0\n Gateway -->|Shard 1: AAPL, TSLA| RB1\n```\n\n1. **Ingestion (Exchange)**:\n * Orders are received and hashed by `SymbolID`.\n * \"Smart Gateway\" logic routes the order to the specific Shard owning that symbol.\n2. **Transport (Ring Buffer)**:\n * Orders are pushed into a lock-free Single-Producer Single-Consumer (SPSC) ring buffer.\n * **Union-Based Commands**: Uses a `union` structure to overlay `Add` and `Cancel` commands, saving memory and fitting more commands per cache line.\n3. **Matching (Core)**:\n * **Flat OrderBook**: Bids and Asks are simple `std::pmr::vector`s indexed directly by price (O(1) lookup).\n * **Matcher**: Iterates linearly over the vector for maximum hardware prefetching efficiency. Active orders are tracked via a `Bitset`.\n4. **Memory Management**:\n * A Monotonic Buffer (Arena) provides memory for new orders. It resets instantly (`release()`) between benchmark runs, preventing fragmentation.\n\n---\n\n## ๐ Build & Run\n\n### Prerequisites\n* C++20 Compiler (GCC 10+ / Clang 12+)\n* CMake 3.14+\n\n### Compiling\n```bash\nmkdir -p build && cd build\ncmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS=\"-march=native\"\nmake -j$(nproc)\n```\n\n### Running Benchmarks\nTo replicate the >160M ops/s performance:\n```bash\n./build/src/benchmark\n```\n\nTo measure **End-to-End Latency** (approximate P50/P99):\n```bash\n./build/src/benchmark --latency\n```\n*Note: Latency mode adds instrumentation overhead and runs usually at ~15-20M ops/sec on M1 Pro due to timestamp calls.*\n\n### Running Verification\nTo ensure the engine is actually matching correctly and not just dropping frames:\n```bash\n./build/src/benchmark --verify\n```\n\n### Real-World Market Replay\nTest the engine against **live Binance L3 data** (Trade + Depth updates) to verify handling of realistic price clustering and bursty order flow.\n\n1. **Record Data** (Requires Python 3 + `websocket-client`):\n ```bash\n # Record 60 seconds of live BTCUSDT data\n python3 scripts/record_l3_data.py 60\n ```\n\n2. **Run Replay**:\n ```bash\n ./build/src/benchmark --replay data/market_data.csv\n ```\n > **Result**: ~132,000,000 orders/sec (M1 Pro) on real-world data.\n\n### Running the Server\n\nStart the engine networking layer (listens on port 8080):\n```bash\n./build/src/OrderMatchingEngine\n```\n\n**Populate the Book (Optional):**\nTo quickly seed the book with Bids, Asks, and Trades for testing/visualization:\n```bash\npython3 scripts/seed_orders.py\n```\n\n---\n\n## ๐ Client Usage (TCP)\n\nConnect using `netcat` or any TCP client.\n\n**Submit Order:**\n```text\nBUY AAPL 100 15000\n> ORDER_ACCEPTED_ASYNC 1\n```\n*(Format: SIDE SYMBOL QTY PRICE_INT)*\n\n**Subscribe to Market Data:**\n```text\nSUBSCRIBE AAPL\n> SUBSCRIBED AAPL\n> TRADE AAPL 15000 50\n```\n\n---\n\n## ๐งช Testing\n\nThe project includes a comprehensive GoogleTest suite covering matching logic, cancellation scenarios, and partial fills.\n\n```bash\n./build/tests/unit_tests\n```\n\n## ๐ Roadmap (Future)\n* **Kernel Bypass**: Integration with DPDK/Solarflare for sub-microsecond wire latency.\n* **Market Data Distribution**: Multicast UDP feed for quote dissemination.\n","default_branch":"main","files":32,"tree":[".clang-format",".clang-tidy",".github/workflows/cmake.yml",".gitignore","CMakeLists.txt","FeedbackAndImprovements.md","LICENSE","README.md","dashboard.py","requirements.txt","run_benchmark.sh","scripts/record_l3_data.py","scripts/seed_orders.py","src/Bitset.hpp","src/CMakeLists.txt","src/Exchange.cpp","src/Exchange.hpp","src/MatchingStrategy.cpp","src/MatchingStrategy.hpp","src/Order.cpp","src/Order.hpp","src/OrderBook.cpp","src/OrderBook.hpp","src/RingBuffer.hpp","src/TcpServer.cpp","src/TcpServer.hpp","src/benchmark.cpp","src/main.cpp","tests/CMakeLists.txt","tests/test_orderbook.cpp","tests/verify_get_book.py","tests/verify_market_data.py"],"storefront":"/r/PIYUSH-KUMAR1809","claimed":false,"request_supported":{"post":"https://gitbuyer.com/r/PIYUSH-KUMAR1809/order-matching-engine/request-supported","requests":0},"note":"indexed from public GitHub; nothing is for sale on this page. Clone it from GitHub. Paid listings live at /search."}