Thread Sanitizer (TSan): Visual walkthrough — Coding deep dive

We use a running story throughout: two threads, A and B, and one shared box of memory called $x$ .

Step 1 — Two threads, one box, and the "who went last?" question

WHAT. Draw time flowing downward. Thread A is one column, thread B is another. Between them sits a single shared memory cell $x$ (think: one number in a box).

WHY. Before we can talk about ordering accesses, we need a picture where "earlier" and "later" mean something. Time-down / threads-across is that picture. Every event (a read, a write, a lock) is a dot in one column.

PICTURE. Look at the two coral/lavender columns. A writes $x$ at one dot; later B writes $x$ at another dot. The whole question of the page is the dashed grey arrow marked "?": is there any chain of events forcing A's write to come before B's write? If no chain exists, the two dots are concurrent, and a write is involved — that is a data race.

Step 2 — Give each thread a private tick counter

WHAT. Give thread A its own counter $C_{A}$ and thread B its own counter $C_{B}$ . Each starts at $0$ . Every time a thread does a synchronization event (a lock, an unlock, a thread start/join), its own counter ticks up by one.

WHY. We need a way to say "this write, not that one." A bare label "A wrote $x$ " is ambiguous if A writes $x$ ten times. A number stamped on each event makes every event uniquely nameable: "A's write at A-time 3." That stamped number is the $k$ from the parent's rule — now you know where it comes from.

PICTURE. Watch the little counter chips beside each column climb $0 \to 1 \to 2$ as sync events fire. The write is tagged with whatever the counter reads at that instant.

A’s private clock C_{A} + = 1 on each of A’s own sync events

Here $C_{A}$ is "how many milestones A has personally passed," and $+ = 1$ is the tick — one milestone at a time, never skipping.

Step 3 — Upgrade to a vector clock: one entry per thread

WHAT. Replace A's single counter with an array $V_{A}$ that has one slot per thread. With two threads it is just two numbers:

V_{A} = [A’s own tick V_{A} [A], latest B-event A is guaranteed to see V_{A} [B]]

$V_{A} [A]$ is A's own milestone count (same as before). $V_{A} [B]$ is the new, crucial slot: "the highest B-time whose effects A is guaranteed to have received."

WHY. The whole race question is "does A's knowledge already cover B's write?" That is a question about B, so A must carry a dedicated number about B. One slot per other thread is the minimum bookkeeping that can answer it. This is the vector clock idea, purpose-built for memory ordering.

PICTURE. Each column now carries a two-cell strip $[\cdot, \cdot]$ . The own cell is solid; the other-thread cell starts empty (value $0$ : "I've heard nothing from B yet").

Step 4 — How knowledge flows: release writes it down, acquire reads it back

WHAT. Synchronization moves knowledge through a shared object $L$ (a mutex). Two mechanical rules, straight from the happens-before axioms:

release (unlock L): V_{L} \leftarrow V_{L} ⊔ V_{A}

acquire (lock L): V_{A} \leftarrow V_{A} ⊔ V_{L}

The symbol $⊔$ means componentwise maximum: for each slot, keep the larger of the two numbers. Reading it term by term: on unlock, A deposits its knowledge into the lock's own clock $V_{L}$ (max keeps the freshest of each slot). On lock, A withdraws whatever fresher knowledge the lock holds.

WHY. This is the mutex turned into arithmetic. Unlock = "I'm done, here's everything I know" (a release in memory-ordering terms). Lock = "before I start, give me everything the last releaser knew" (an acquire). Max, and only max, correctly merges two histories without losing any milestone.

PICTURE. Follow the mint arrow: A's strip flows into the lock chip on unlock; later B's lock pulls the lock chip into B's strip. After that pull, B's "about-A" cell finally holds a real number instead of $0$ .

[3, 0] ⊔ [0, 1] = [max (3, 0), max (0, 1)] = [3, 1]

Each slot is maxed independently — that is why B ends up knowing both A's milestone 3 and its own milestone 1.

Step 5 — The race check as one comparison

WHAT. When thread A accesses $x$ , TSan looks at the shadow record of a previous access: "B wrote $x$ at B-time $k$ ." The verdict:

race ⟺ (at least one is a write) \land (V_{A} [B] < k)

Term by term: $V_{A} [B]$ is "how much of B's timeline A is guaranteed to see." $k$ is "the B-time of that earlier write." If A's knowledge falls short of $k$ ( $V_{A} [B] < k$ ), then B's write is not in A's past — it is concurrent. Add a write, and it is a race.

WHY this comparison and not another? We chose < because "ordered" means exactly "already covered by my knowledge." If $V_{A} [B] \geq k$ , A's slot has reached or passed B's write — a happens-before edge got the news to A, so the two are ordered and safe. The single inequality is the entire happens-before test compressed into one number-vs-number.

PICTURE. Two panels side by side. Left (RACE): B wrote at $k = 1$ but A's about-B cell is still $0$ — $0 < 1$ , whistle. Right (SAFE): a mutex ran between them, so A's about-B cell is now $1$ — $1 \geq 1$ , silent.

Step 6 — Edge case: two reads never race

WHAT. Suppose both accesses to $x$ are reads, and $V_{A} [B] < k$ (genuinely concurrent). Still no race.

WHY. The rule has an $\land (at least one write)$ guard. Two reads leave the value untouched, so the final contents of $x$ don't depend on their order. Concurrency alone is harmless; concurrency plus a write is the danger. This is why the parent insists on "at least one write."

PICTURE. Both dots are reads (open circles). The concurrency arrow is still dashed-grey — but the whistle is crossed out, because the write-guard fails.

Step 7 — Edge case: `volatile` looks like a fix but moves no knowledge

WHAT. Declare volatile int x; and race on it anyway. TSan still whistles.

WHY. volatile only tells the compiler "don't cache this in a register." It performs no release and no acquire — it never runs the $⊔$ merge of Step 4. So B's about-A cell stays at $0$ ; $V_{B} [A] < k$ remains true; the check still fires. The cure is a real synchronizing tool (std::atomic or a mutex) that actually executes the merge. Skipping it is textbook undefined behavior.

PICTURE. The lock chip from Step 4 is replaced by a volatile tag that is transparent — the knowledge arrow passes straight through and deposits nothing. B's about-A cell stays empty.

Step 8 — Edge case: `join` is a release/acquire in disguise

WHAT. Thread A writes $x$ , then the main thread calls pthread_join(A), then reads $x$ . No race.

WHY. join is defined to acquire everything the joined thread released on exit. Mechanically: A's exit is a release ( $V_{A}$ deposited), the return of join is an acquire ( $V_{main} \leftarrow V_{main} ⊔ V_{A}$ ). After that merge $V_{main} [A] \geq k$ , so the later read is safely ordered — the exact same machinery as a mutex, just spelled differently.

PICTURE. A's whole strip flows across the join barrier into the main thread; the about-A cell fills up before the read.

The one-picture summary

WHAT. One diagram compressing all eight steps: the two-column timeline, the vector strips ticking, a mutex depositing/withdrawing knowledge, and the final $V_{A} [B]$ vs $k$ comparison branching into RACE or SAFE.

Recall Feynman: the whole walkthrough in plain words

Picture two kids editing one shared line in a notebook. Each kid keeps a little scorecard with two numbers: "my own turn count" and "the last turn of the other kid I was actually told about." Whenever a kid finishes and passes the notebook (that's a lock/unlock, or a join), they hand over their whole scorecard — the other kid copies down any number bigger than what they had. Now the hall monitor's whole job is one glance: when a kid touches the shared line, check the scorecard cell for the other kid against the turn-number stamped on the other kid's last edit. If your cell is smaller, you were never told about that edit — you're editing blind. If someone's edit was a write, the monitor blows the whistle: collision possible. Two reads? No whistle — nobody changed anything, order can't matter. volatile? Still a whistle — it's a kid who never passes the notebook, so nobody's scorecard ever updates. join? Silent — it's just a formal handoff of the whole scorecard. Every case on this page is that same one glance: my knowledge of you vs. your last stamp.

See also: Thread Sanitizer (TSan) · Vector Clocks · Data Race vs Race Condition · Memory Models · std::atomic and Memory Ordering · Mutexes and Locks · AddressSanitizer (ASan) · Undefined Behavior in C and C++