This repository has been archived on 2026-11-16. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
orderbook-collector/docs/adr/0001-concurrency-model.md
T
pascal 02747b882f feat(polymarket)!: two connections per market, first one wins
Every live market is subscribed on two connections chosen at random, and its
book takes each change from whichever connection delivers it first: the book
hash says whether a change is a duplicate, the next one, or one to hold until
the change before it arrives. A change one connection misses costs nothing,
each Delta carries the earliest receive time, and a connection that drops is
covered by the other. When a change fits on no connection in time, the book
follows one connection unchecked and asks the other for a fresh book.
Connections now decode and route events to 16 book threads, independent of
them; a move leaves its old connection only once the new one delivers, so it
costs no change; a connection closed with 1013 twice within ten minutes is
split. reconcile reads the collector's log and fails only on a mismatch no
cause line explains. SIGTERM and SIGHUP stop the collector cleanly.

Breaking: lanes are gone (connections and book threads are separate), and
reconcile takes the log as a second argument.
2026-11-11 15:18:48 +00:00

40 lines
2.0 KiB
Markdown

# 0001. Concurrency model: threads, shared-nothing
## Context
The collector moves a firehose of websocket messages from many sockets to a
single output sink. This is the project's central bet (see
[../project.md](../project.md)): it must be correct (no dropped messages, no
races) and time-accurate (receive time stamped at the socket edge) before it is
fast. The runtime is the one foundational, costly-to-change choice. The template
already uses `std` threads + `crossbeam` channels and pulls in no tokio.
## Decision
V1 uses **OS threads**, not an async runtime — a sync websocket client
(`tungstenite`), with one read loop per socket. State is **shared-nothing**: no
mutexes. Each pipeline stage either owns its state on a single thread or is
sharded so each shard owns its slice, and stages communicate over channels.
Async (tokio) is deferred as a possible optimization, re-evaluated at the start
of extension 1 (M4), when socket-management complexity (reconnect, timeouts,
redundancy) makes async ergonomics worth their cost.
## Why
Thread-per-socket is comfortable at this scale (symbols shard across tens of
sockets, not thousands) and is the simplest, most readable option — correctness
first, speed later. Shared-nothing + channels removes lock contention and data
races by construction, and keeps the runtime pluggable: only the socket layer is
runtime-specific, so a later async swap is localized to that boundary rather than
a pipeline rewrite. Deferring async is therefore safe through the base challenge.
The M4 checkpoint was held in sprint 04 (2026-11-11): threads stay. The new
logic of redundancy sits in the book threads, not in socket handling, and
about 200 threads (175 connections, 16 book threads) are comfortable.
Trade-off: thread-per-socket does not scale to very large socket counts, and the
extension-era socket-management logic (select / timeout / reconnect) is where
threads and async diverge most — hence the explicit M4 re-evaluation point rather
than "never."