Detecting Data Races with Thread Sanitizer

In this lesson, you will learn how to automate the detection of elusive data races in your concurrent Rust systems by integrating the LLVM Thread Sanitizer (TSan) into your CI pipeline.

While Miri is excellent for verifying unsafe code, it can be extremely slow for large-scale test suites. The Thread Sanitizer, conversely, is a dynamic analysis tool that monitors memory access during actual execution. It flags data races—situations where two threads access the same memory location concurrently, at least one is a write, and there is no synchronization—with very low overhead compared to an interpreter.

Enabling TSan in Your Workflow

To leverage TSan, your project must be compiled with the -Z sanitizer=thread flag. Since this requires nightly Rust, you can set it up in your CI environment by ensuring the rust-src component is installed:

rustup component add rust-src --toolchain nightly
export RUSTFLAGS="-Z sanitizer=thread"
cargo test --target x86_64-unknown-linux-gnu

Catching a Race

Consider a simple shared counter that lacks an Atomic or Mutex wrapper:

use std::thread;

fn main() {
    let mut data = 0;
    let handle = thread::spawn(move || {
        data += 1; // Potential data race
    });
    data += 1; // Potential data race
    handle.join().unwrap();
}

If you run this with TSan enabled, the tool will intercept the memory operations at runtime. It will output a clear report detailing the stack traces of both threads involved in the conflicting access, identifying exactly where your synchronization strategy failed.

Integrating into CI

For CI pipelines (like GitHub Actions), you should dedicate a specific job to this check. Because TSan only works on Linux and requires specific compilation flags, keep this as a separate step from your standard cargo test run. By forcing this check on pull requests, you ensure that complex, intermittent race conditions are caught before they ever reach your production environment, providing a safety net that complements your manual Send and Sync trait implementations.

Key Takeaway: Thread Sanitizer turns silent, non-deterministic data races into loud, actionable error reports by instrumenting your binaries to monitor memory access patterns during test execution.