The sequencer and determinism
A number rather than a time, an engine that reads only its inputs, and what that makes possible.
Lesson 48 min
By the end of this lesson
- Explain why the sequence number, not the time, sets the processing order
- Spot a read in code that breaks the engine’s determinism
- Place the writing of an entry to the log before the engine processes it
Two brokerage firms send an order in the same millisecond, each through its own gateway. Opposite, there is only enough to fill one. Who wins? It cannot be "whoever arrived first": to the millisecond, nobody arrived first. What you will learn here: a single sequencer gives each input a final number, and an engine that reads only these numbered inputs is deterministic.
A number rather than a time
Sequencer
The single component that receives messages from all gateways, puts them in one queue and gives each a final sequence number, written to the log before any processing.
Time is not enough to order things: two clocks never show quite the same time, and two messages can carry the same millisecond. The BVMAC timestamps each order on receipt by the brokerage firm (RG BVMAC 2025, art. 150); the 2008 draft instruction also provided "a sequential order number per security" assigned by the system (instruction no. 2, 2008). The time says when; the number says in which order.
Gateways
-
Sequencer queue
seq 1 · e1
A sell is waiting
In the animation, why does the result change when you change the sequencer order, even though both orders 'arrived' in the same millisecond?
Determinism, a discipline
An engine is deterministic if the same sequence of inputs always gives the same sequence of outputs (developer track, An engine's invariants). This does not come by itself. The engine must read nothing that is not in the input:
- no clock:
Date.now()gives a different value on each replay; the time is set by the sequencer in the input, then logged; - no randomness: no
Math.random(); if needed, a logged seed; - no floats for prices: integers, as in
@criee/marche(Modelling an order); - no accidental order: iterating over a collection whose order depends on the implementation, or processing two inputs that touch the same book in parallel.
The architecture published by the LMAX venue in 2011 takes this idea to its end: all business logic runs on a single thread, in memory, inputs are logged before processing, and "the current state [...] is entirely derivable by processing the input events" (Martin Fowler, "The LMAX Architecture"). A single thread is not compulsory; never letting two threads decide the order together is.
import { Carnet, type Execution, type Ordre } from '@criee/marche'
interface Entree { seq: number; horodatage: string; ordre: Omit<Ordre, 'rang'> }
class Sequenceur {
private suivant = 1
constructor(private horloge: () => string, private journal: Entree[]) {}
/** Single entry point: numbers, timestamps, logs, then returns the input. */
recevoir(ordre: Omit<Ordre, 'rang'>): Entree {
const e = { seq: this.suivant++, horodatage: this.horloge(), ordre }
this.journal.push(e) // written before any processing
return e
}
}
/** The engine sees only inputs: no clock, no network, no randomness. */
function appliquer(carnet: Carnet, e: Entree): Execution[] {
return carnet.passer(e.ordre)
}
The clock is injected: in production it reads system time; in tests it returns a fixed sequence. The engine never sees it.
Who gets filled?Fictional
A fictional sell of 30 shares at 10,050 rests in the book (number 1). At 09:30:00.000 arrive: Alpha, a buy of 30 at 10,100; Beta, a buy of 30 at 10,050.
Sequence A (Alpha number 2, Beta number 3):
- Alpha meets the sell: 30 shares at 10,050, the resting order's price. Amount 30 × 10,050 = 301,500 XAF.
- Beta finds nothing left: it rests in the book, 30 at 10,050.
Sequence B (Beta 2, Alpha 3):
- Beta takes the 30 shares at 10,050, the same 301,500 XAF.
- Alpha rests in the book, 30 at 10,100.
Same time, two sequences, two results. Each one, replayed a hundred times, gives the same result a hundred times.
What determinism makes possible
Determinism is not an elegance: three mechanisms in the next lessons depend on it.
- Recovery after a crash: a secondary replays the log and reaches the primary's state (lesson 7).
- Comparative replay: the old and the new engine receive the same log, and any difference in output is a defect (lesson 9).
- Proof: in a dispute, the session is replayed to show why a given order was filled (lesson 8).
Name two sources of non-determinism an engine must forbid itself, and what replaces them.
Your turn
Read next: Martin Fowler, « The LMAX Architecture » (2011)
A question? Ask your teacher, or an AI assistant, giving it the title of this lesson.