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
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 |
- 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:
mmapplusmprotectguard 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().
- Parser: in-place cast of wire messages into
OrderEntry,OrderCancel, andExecutionReport. - LimitOrderBook: flat array of price levels, occupancy bitset, intrusive FIFO list per level,
best_bid_andbest_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.
position-risk/ contains headers and TODO notes only. No implementation.
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.
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.
├── 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