ThreadSanitizer triage: recover the missing synchronization contract

What it is

ThreadSanitizer detects data races using compiler instrumentation and a runtime library. Clang documents -fsanitize=thread for compilation and linking, with debug information for actionable source locations. The report connects conflicting accesses and thread creation context; it is evidence about an executed concurrent interaction, not a complete specification of the intended algorithm. Clang ThreadSanitizer

Why it matters

A coding agent can silence a report by surrounding the named line with a lock while leaving other accesses outside the same discipline. Instead, identify who owns the state, when ownership transfers, and what synchronization establishes access order. A coherent rule should explain every path touching the object.

How to apply

• Read both access stacks and locate the shared object. Separate its construction, ordinary updates, publication and destruction; lifetime errors can cross the same thread boundary as updates.
• State the intended contract: exclusively owned by one thread, protected by one named mutex, or communicated through a specified synchronization mechanism. Compare all accesses with that contract.
• Make the smallest change that restores the contract. If replacing shared mutation with message passing, document who owns the object before and after delivery.
• Propose a fixture that deliberately coordinates the competing operations, avoiding arbitrary sleeps as the only mechanism for exercising overlap. Include shutdown or cancellation if the reported interaction occurs there.
• Rerun the relevant instrumented workload and the ordinary suite. Record excluded or uninstrumented components and any suppression that limits the conclusion.

Pitfalls

A race-free implementation can still have logical ordering bugs or deadlocks. A clean run also does not prove every scheduling interleaving was exercised. Instrumentation and ignorelists affect what the tool observes; the documentation warns that omitted instrumentation can obscure synchronization and stack information. Treat a suppression as a scoped limitation to explain, not as evidence that the underlying ownership rule is correct.