Skip to content
This repository was archived by the owner on Oct 22, 2026. It is now read-only.
vyaykumarPublic archive

About

A C++23 data transport and orchestrator that connects an upstream high-frequency trading client to a downstream matching engine.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Project Icarus: Technical Specification

Status: Archived at archive/v1.0-final (3a8987a)

Language: C++20 (shared headers, per the archive README)

Platform: Linux, WSL2 kernel 6.18.33.2-microsoft-standard-WSL2

Compiler: g++ 15.2.0

Subsystems

1. shared/: reusable primitives

Header-only, zero-allocation on the hot path, no domain dependencies. Each header compiles under g++ -std=c++20 -O2 -Wall -Wextra -Wpedantic -Werror -pthread.

Header Component Function Hot-path cost
ring_buffer.h RingBuffer<T, Cap> Lock-free SPSC ring, alignas(64) head and tail Push ~6 ns, pop ~1 ns
free_list_pool.h FreeListPool<T, Cap> O(1) LIFO free list, Handle{index, generation} O(1) allocate and free
flat_hash_map.h FlatHashMap<V, MaxElem> Fixed-capacity open addressing, SplitMix64, linear probing No heap allocation
guarded_memory_pool.h GuardedMemoryPool<T, Cap> Page-aligned mmap with trailing mprotect(PROT_NONE) guard page Zero runtime cost, SIGSEGV on overrun
affinity.h pin_calling_thread_to_core, bind_thread_to_core pthread_setaffinity_np with sched_getcpu() verification Setup only
busy_poll.h cpu_relax(), governor warmup _mm_pause on x86, yield on ARM Spin loop
latency_harness.h Percentile harness Interpolated P50 to P99.99, calibrate_steady_clock_ns(), hardware metadata Offline
memory_tracker.h Allocation tracker Lock-free global new/delete override, RAII ScopedAllocationScope Instrumentation

2. Transport layer (Phases 1 to 3)

  • Event: 64-byte packed struct. Timestamp, sequence number, payload handle, 32-byte inline payload.
  • RingBuffer: SPSC queue, power-of-two capacity, acquire/release ordering, usable capacity Capacity - 1.
  • MemoryPool: generation-checked pool with use-after-free detection.
  • FreeListPool: O(1) allocation, replaces linear search.
  • GuardedMemoryPool: mmap plus mprotect guard page.
  • Publisher and Subscriber: test harnesses, pinned to cores 1 and 2.
  • IngressReceiver: abstract source interface, poll(buffer, max_len).
  • MockIngressSource: deterministic synthetic 128-byte order frames.
  • EventDirector: poll, allocate, copy, push, busy-polled with _mm_pause().

3. Matching engine (Phase 4)

  • Parser: in-place cast of wire messages into OrderEntry, OrderCancel, and ExecutionReport.
  • LimitOrderBook: flat array of price levels, occupancy bitset, intrusive FIFO list per level, best_bid_ and best_ask_ tracking.
  • Matcher: order entry, cancellation, cancel-replace, execution report generation.
  • Dispatcher: routes parsed messages to the matcher.

Implemented features:

  • Limit orders with price-time priority
  • Partial fills across multiple price levels
  • Cancellation and cancel-replace
  • Best-price maintenance on level exhaustion
  • Deterministic replay, bit-exact across warm runs
  • Invariant audit: FIFO order, spread integrity, volume conservation
  • Zero heap allocation on the matching path

Not connected: the transport-layer subscriber does not call the dispatcher.

4. Position and risk (Phase 5)

position-risk/ contains headers and TODO notes only. No implementation.

Benchmarks

Source: results/ CSVs, environment per archive README.

Environment: Intel Core i3-1220P (6 cores, 12 threads), WSL2, g++ 15.2.0, -O2 -g Release. Steady clock calibrated, timer floor 18 ns P50.

Scenario Workload Throughput P50 P90 P99 P99.99 Heap allocations
A: Ingestion 100K sequential orders 13.06M/s 40 ns 106 ns 173 ns 1,529 ns 0
B: Cancellation 50K cancel events 11.39M/s 44 ns 116 ns 193 ns 1,424 ns 0
C: Replacement 50K cancel-replace pairs 7.59M/s 83 ns 178 ns 282 ns 2,467 ns 0
D: Partial fills 1 to 100 levels ~14 ns/fill 169 ns 219 ns 336 ns 1,650 ns 0
E: Cancel cascades Head, random, tail (5K) n/a 41 to 46 ns 46 to 81 ns 57 to 284 ns 163 to 423 ns 0
F: Sustained load 1 s, 2.23M ops 2.23M/s 78 ns 1,764 ns 4,778 ns 14,753 ns 0
G: Worst case Max spread traversal n/a 56 ns 272 ns 522 ns 752 ns 0
H: Determinism 100K events, 3 warm replays 12.52M/s 43 ns 95 ns 142 ns 237 ns 0, bit-exact
I: Invariant audit 250K checks 9.56M/s 46 ns 116 ns 185 ns 1,158 ns 0, all valid
J: Custom flat book 100K operations 13.41M/s 40 ns 110 ns 159 ns 278 ns 0
J: std::map baseline 100K operations 12.67M/s 49 ns 102 ns 141 ns 228 ns 51,980

Ring buffer baseline (Phase 1): 26 ns minimum, 3.8 µs median, 95 µs P99, 13.6M events/s, 1M events, 64 KB buffer. Measures queue residence time under saturation.

Ingress (Phase 3): P50 24 ns, P95 25 ns, P99 35 ns, 94.5K events/s.

Full methodology: METHODOLOGY.md.

Build

cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure
g++ -std=c++20 -O2 -Wall -Wextra -Wpedantic -Werror -pthread -I. shared/ring_buffer.h

File Tree

.
├── README.md
├── METHODOLOGY.md
├── CMakeLists.txt
├── shared/
│   ├── ring_buffer.h
│   ├── free_list_pool.h
│   ├── flat_hash_map.h
│   ├── guarded_memory_pool.h
│   ├── affinity.h
│   ├── busy_poll.h
│   ├── latency_harness.h
│   └── memory_tracker.h
├── results/
│   ├── baseline_ingestion.csv
│   ├── order_cancellation.csv
│   ├── order_replacement.csv
│   ├── partial_fill_chains.csv
│   ├── cancellation_cascades.csv
│   ├── sustained_throughput.csv
│   ├── worst_case_traversal.csv
│   ├── deterministic_replay.csv
│   ├── invariant_audit.csv
│   └── book_comparison.csv
├── transport-layer/
│   ├── CMakeLists.txt
│   ├── include/transport_layer/
│   │   ├── transport/       event.h, event_bus.h, ring_buffer.h, memory_pool.h
│   │   ├── memory-pool/     free_list_pool.h
│   │   ├── guarded-pool/    guarded_memory_pool.h
│   │   ├── core/            affinity.h
│   │   ├── publisher/       publisher.h
│   │   ├── subscriber/      subscriber.h
│   │   └── ingress/         ingress.h, mock_ingress.h, event_director.h
│   └── tests/
├── engine/
│   ├── CMakeLists.txt
│   ├── include/engine/
│   │   ├── book/            level.h, side.h, book.h
│   │   ├── core/            matcher.h, types.h
│   │   ├── protocol/        wire.h, parser.h
│   │   └── dispatch/        dispatcher.h
│   ├── tests/               test_book.cpp, test_matcher.cpp,
│   │                        test_parser.cpp, test_dispatch.cpp
│   └── bench/
│       ├── CMakeLists.txt
│       ├── engine_bench.cpp
│       ├── dispatcher_bench.cpp
│       ├── common/          benchmark_utils.h, memory_tracker.h, memory_tracker.cpp
│       ├── book/            scenario_book_depth.cpp, scenario_comparison.cpp
│       ├── workload/        scenario_arrival_patterns.cpp,
│       │                    scenario_workload_mix.cpp,
│       │                    scenario_partial_fills.cpp,
│       │                    scenario_cancellations.cpp
│       ├── stress/          scenario_sustained_load.cpp,
│       │                    scenario_worst_case.cpp
│       ├── validation/      scenario_deterministic.cpp,
│       │                    scenario_invariants.cpp
│       └── results/         runtime CSV output
└── position-risk/           scaffold only

About

A C++23 data transport and orchestrator that connects an upstream high-frequency trading client to a downstream matching engine.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Contributors

Languages