并发程序调试技巧

说实话，调试并发程序的痛苦程度，只有亲自踩过坑的人才能理解。单线程程序的 bug 好歹是确定性的——你给定同样的输入，它一定在同一个地方以同样的方式炸掉。但并发 bug 不是这样。数据竞争可能跑一万次才出现一次，死锁可能只在某个特定的线程调度顺序下才触发，而且它总是"在你这里没问题，在 CI 上必挂"。笔者曾经为一个 data race 搞了整整两天，最后发现是一个 lambda 捕获了局部变量的引用——这种 bug 你光看代码根本看不出来，因为单线程执行路径下它完全正确。

这一篇我们要做的是建立一套系统性的并发调试方法论。不是"加个 print 看看"那种，而是从理解 bug 的分类特征开始，到选择正确的工具，再到读懂工具的报告，最后形成可复现、可验证的修复流程。我们会重点介绍 ThreadSanitizer（TSan）、Valgrind 的 Helgrind 工具、Clang 的编译期线程安全分析，以及一个实际可用的结构化日志方案。

环境说明

这篇里所有的命令和代码都在以下环境下测试通过：Ubuntu 22.04 LTS（WSL2 亦可），编译器使用 Clang 16+ 或 GCC 12+（需要 TSan 支持），Valgrind 3.18 以上版本（apt install valgrind 即可），调试器是 GDB 12+，如果你用 CMake 管理项目则需要 3.20 以上版本。如果你的发行版比较旧，TSan 的报告格式可能略有不同，但核心内容是一致的。

并发 bug 的四大门派

在开始用工具之前，我们需要先搞清楚并发 bug 大致分为哪几类，因为不同类型的 bug 对应的诊断策略完全不同。

**数据竞争（data race）**是最常见也最阴险的一类。它的定义很严格：两个或以上的线程同时访问同一个内存位置，其中至少一个是写入操作，而且它们之间没有任何同步关系（没有 mutex、没有 atomic、没有 happens-before）。C++ 标准明确规定数据竞争是未定义行为——不是"可能出错"，是"什么都可能发生"，包括但不限于读到垃圾值、程序崩溃、甚至看起来"正常工作"然后突然在某一天爆炸。数据竞争之所以难以追踪，是因为它取决于线程的调度顺序，而这个顺序在你调试的时候和在生产环境里可能完全不同。你加一个 printf 调试，打印本身就改变了时序，bug 就消失了——这就是经典的"Heisenbug"。

**死锁（deadlock）**是另一大类。两个或多个线程互相等待对方持有的资源，谁也不让步，程序就彻底卡死了。死锁的确定性其实比数据竞争高——只要触发了特定的锁获取顺序，它必定发生。但问题在于，触发条件可能非常复杂，涉及多个线程的特定执行路径组合。而且死锁往往在正常负载下不出现，只在某些特定的并发模式下才暴露。

**活锁（livelock）**比死锁更隐蔽。线程们没有卡死——CPU 占用率可能是 100%——但没有任何有意义的进展。一个经典的例子是两个线程都在礼貌地让出资源给对方，结果谁也没拿到。活锁的表象是程序变慢而不是卡死，很容易被误判为性能问题。

最后是悬挂引用（dangling reference）。线程通过引用或指针访问了一个已经超出生命周期的对象——这在异步编程中尤其常见。比如你启动一个线程，传了一个局部变量的引用进去，然后函数返回了，局部变量被销毁，线程还在用那个引用。这种 bug 的表现取决于那块内存被重新分配给了什么——可能读到一个"看起来正常但其实是错的"值，也可能直接 segfault。

Bug 类型	核心特征	复现难度	典型信号
数据竞争	未同步的并发读写	极高（时序依赖）	间歇性错误结果、Heisenbug
死锁	循环等待资源	中高（路径依赖）	程序完全卡死
活锁	反复让步无进展	中	CPU 100% 但无输出
悬挂引用	访问已销毁对象	高（内存状态依赖）	间歇性崩溃、垃圾值

ThreadSanitizer：数据竞争的克星

原理：编译器插桩

ThreadSanitizer（简称 TSan）的工作方式是在编译期对你的代码进行插桩（instrumentation）。当你加上 -fsanitize=thread 编译选项时，编译器会在每个内存访问（读和写）前后插入额外的检查代码。运行时，这些检查代码会维护一个"影子内存"（shadow memory），记录每个内存位置的访问历史和同步事件。

TSan 使用的是一种基于 happens-before 关系和锁集分析（lockset analysis）的混合算法。简单来说，它追踪每次内存访问的线程 ID 和一个逻辑时间戳（向量时钟），同时追踪哪些 mutex 被当前线程持有。如果它发现两个来自不同线程的内存访问没有 happens-before 关系（也就是它们之间没有任何同步操作），而且至少一个是写入，它就会报告一个数据竞争。这个算法的理论基础保证了：如果一个数据竞争在你的测试执行中确实发生了（哪怕只发生一次），算法层面一定能检测到它。不过要注意，TSan 的实现为每个 8 字节内存位置维护有限大小的历史缓冲区，在极端情况下（比如大量线程频繁访问同一地址导致旧记录被淘汰），实际漏检率非常低但不为零。对于绝大多数真实场景，你可以把"TSan 没报"当作"这段执行路径上确实没有 data race"的强信号。

启用 TSan

启用 TSan 非常简单，只需要在编译时加上对应的 flag：

bash

# 编译时加上 -fsanitize=thread 和调试信息
clang++ -fsanitize=thread -g -O1 -pthread your_program.cpp -o your_program

# 或者 GCC
g++ -fsanitize=thread -g -O1 -pthread your_program.cpp -o your_program

这里有几个要注意的点。第一，-g 必须加，否则 TSan 报告里只有地址没有源码位置，你很难定位问题。第二，官方推荐用 -O1 或更高，主要是为了性能——TSan 本身就有 5-15 倍的 slowdown，-O0 的无优化代码会让开销雪上加霜；但也别用 -O2 或更高，因为激进优化可能内联太多函数导致栈追踪变得难以阅读。第三，TSan 不支持和 AddressSanitizer（ASan）同时使用，如果你的构建脚本里同时开了这两个，编译器会直接报错。

如果你用 CMake，可以这么配置：

cmake

# CMakeLists.txt 中启用 TSan
option(ENABLE_TSAN "Enable ThreadSanitizer" OFF)

if(ENABLE_TSAN)
    add_compile_options(-fsanitize=thread -g -O1)
    add_link_options(-fsanitize=thread)
endif()

然后 cmake -DENABLE_TSAN=ON .. 即可。

实战：一个 data race 的完整诊断

让我们来看一个经典的 data race 场景，然后一步步用 TSan 抓出来。

cpp

#include <thread>
#include <vector>
#include <iostream>

class ThreadSafeCounter {
public:
    void increment()
    {
        // 看起来人畜无害，实际上这里有 data race
        count_++;
    }

    int get() const { return count_; }

private:
    int count_{0};
};

int main()
{
    ThreadSafeCounter counter;
    constexpr int kIterations = 100000;

    auto worker = [&counter]() {
        for (int i = 0; i < kIterations; ++i) {
            counter.increment();
        }
    };

    std::vector<std::thread> threads;
    for (int i = 0; i < 4; ++i) {
        threads.emplace_back(worker);
    }

    for (auto& t : threads) {
        t.join();
    }

    // 期望 400000，实际上几乎不可能得到这个值
    std::cout << "Final count: " << counter.get() << "\n";
    return 0;
}

这段代码的问题很明显——count_++ 不是原子操作，四个线程同时递增它就会丢数据。但问题在于，如果不加 TSan，你看到的只是"结果不对"（比如输出 287541 而不是 400000），你无法确定这是 data race 还是逻辑错误。加上 TSan 之后：

bash

clang++ -fsanitize=thread -g -O1 -pthread counter.cpp -o counter
./counter

TSan 的输出大致如下（具体行号会因你的代码而异）：

text

==================
WARNING: ThreadSanitizer: data race (pid=12345)
  Write of size 4 at 0x7b0c00000000 by thread T2:
    #0 ThreadSafeCounter::increment() counter.cpp:10:9 (counter+0x4a2b)
    #1 main::$_0::operator()() const counter.cpp:24:13 (counter+0x4a03)

  Previous write of size 4 at 0x7b0c00000000 by thread T1:
    #0 ThreadSafeCounter::increment() counter.cpp:10:9 (counter+0x4a2b)
    #1 main::$_0::operator()() const counter.cpp:24:13 (counter+0x4a03)

  Location is stack of main thread.

  Thread T2 (tid=12347, running) created by main thread at:
    #0 pthread_create <null> (counter+0x42278)
    #1 main counter.cpp:28:23 (counter+0x4b0e)

  Thread T1 (tid=12346, finished) created by main thread at:
    #0 pthread_create <null> (counter+0x42278)
    #1 main counter.cpp:28:23 (counter+0x4b0e)
SUMMARY: ThreadSanitizer: data race counter.cpp:10:9 in ThreadSafeCounter::increment()
==================
Final count: 287541

我们来拆一下这份报告。最上面一行 WARNING: ThreadSanitizer: data race 告诉你这是一个数据竞争。然后它给出了两次冲突的访问：一次是 T2 线程的写入（Write of size 4），发生在 counter.cpp:10:9，也就是 count_++ 那一行。另一次是 T1 线程的先前写入（Previous write），发生在同一位置。这恰好是 data race 的标准定义——两个线程同时写入同一个内存位置，没有同步。最后它还告诉你线程是在哪里被创建的（main counter.cpp:28:23），帮你追踪整个调用链。

修复方法很简单——用 std::atomic<int> 或者加 mutex：

cpp

#include <atomic>

class ThreadSafeCounter {
public:
    void increment()
    {
        // 使用 atomic，data race 消失
        count_.fetch_add(1, std::memory_order_relaxed);
    }

    int get() const
    {
        return count_.load(std::memory_order_relaxed);
    }

private:
    std::atomic<int> count_{0};
};

重新编译运行，TSan 不再报告任何问题，输出也稳定为 400000。

TSan 的局限

TSan 好用，但它不是万能的，我们必须清楚它的限制。

首先，性能开销很大。TSan 的典型开销是 5-15 倍的运行时间 slowdown 和 5-10 倍的内存开销。这意味着你不能在生产环境开着 TSan 跑——它只能用于测试和 CI。好消息是，你不需要在生产环境跑，因为 TSan 检测的是代码逻辑问题，不是运行时环境问题。

其次，TSan 只能检测到在你的测试中实际执行到的代码路径上的 data race。如果你的测试覆盖率不够，有些竞争可能永远不会被触发。所以配合 TSan 使用时，你的并发测试需要尽可能覆盖各种线程交错的情况——比如用不同的线程数量、不同的任务粒度多跑几轮。

还有一个容易被忽视的问题：TSan 对自定义同步机制的识别有限。如果你自己实现了一个基于 std::atomic 的自旋锁或者屏障，但没有使用 TSan 提供的注解接口（__tsan_acquire / __tsan_release），TSan 可能会误报（把你的自定义同步当作没有同步）或者漏报。对于标准的 std::mutex、std::atomic、std::condition_variable 等，TSan 都能正确识别；但如果你有自定义的同步原语，需要额外处理。

⚠️ 注意：TSan 和 ASan 不能同时启用。如果你的项目已经用 ASan 做内存错误检测，需要单独构建一个 TSan 版本。通常的做法是在 CI 里跑两套测试——一套 ASan，一套 TSan。

Helgrind：Valgrind 的线程错误检测

原理与使用

Helgrind 是 Valgrind 工具集中的一个线程错误检测器。和 TSan 的编译期插桩不同，Valgrind 采用的是动态二进制插桩（dynamic binary instrumentation, DBI）——它不需要重新编译你的程序，而是在运行时动态地分析每一条指令。

Helgrind 使用基于 happens-before 的锁集分析。它追踪程序中所有 pthread 同步操作（mutex lock/unlock、thread create/join、condition variable signal/wait），构建线程间的 happens-before 关系图。同时，它为每个线程维护一个"锁集"（当前持有的锁的集合），并在每次内存访问时检查：如果两个线程访问同一内存位置且锁集的交集为空（也就是没有共同的锁保护），就报告一个潜在的数据竞争。

此外，Helgrind 还会构建一个"锁顺序图"（lock order graph）。如果它观察到锁 A 在锁 B 之前被获取（形成了 A -> B 的边），后来又在另一个线程中观察到 B -> A 的顺序，图中就出现了环——这就是潜在的死锁。

使用 Helgrind 不需要重新编译，直接运行即可：

bash

valgrind --tool=helgrind ./your_program

如果你的程序接受命令行参数，加在最后就行：

bash

valgrind --tool=helgrind ./your_program --arg1 --arg2

实战：锁顺序错误

来看一个经典的锁顺序问题——两个线程以不同的顺序获取两把锁，这是死锁的温床。

cpp

#include <mutex>
#include <thread>
#include <iostream>

class BankAccount {
public:
    explicit BankAccount(int balance) : balance_(balance) {}

    void transfer_from(BankAccount& other, int amount)
    {
        // 先锁自己，再锁对方
        std::lock_guard<std::mutex> lk1(mutex_);
        std::lock_guard<std::mutex> lk2(other.mutex_);

        if (other.balance_ >= amount) {
            other.balance_ -= amount;
            balance_ += amount;
        }
    }

    int get_balance() const
    {
        std::lock_guard<std::mutex> lk(mutex_);
        return balance_;
    }

private:
    mutable std::mutex mutex_;
    int balance_;
};

int main()
{
    BankAccount alice(1000);
    BankAccount bob(1000);

    // alice 向 bob 转 100
    std::thread t1([&]() {
        for (int i = 0; i < 100; ++i) {
            alice.transfer_from(bob, 1);
        }
    });

    // bob 向 alice 转 100
    std::thread t2([&]() {
        for (int i = 0; i < 100; ++i) {
            bob.transfer_from(alice, 1);
        }
    });

    t1.join();
    t2.join();

    std::cout << "Alice: " << alice.get_balance()
              << ", Bob: " << bob.get_balance() << "\n";
    return 0;
}

这个程序有概率死锁：t1 先锁 alice 再锁 bob，t2 先锁 bob 再锁 alice。如果 t1 锁住 alice 的同时 t2 锁住了 bob，两个人都在等对方释放——经典死锁。用 Helgrind 跑一下：

bash

g++ -g -O1 -pthread transfer.cpp -o transfer
valgrind --tool=helgrind ./transfer

Helgrind 会输出类似这样的报告：

text

---Thread-Announcement ---
Thread #1 is the program's root thread

---Thread-Announcement ---
Thread #2 was created
   at 0x4C3A0E3: pthread_create (helgrind_intercepts.c:xxx)
   by 0x401234: main (transfer.cpp:38)

---Thread-Announcement ---
Thread #3 was created
   ...

--- Lock order violation ---
Possible data race during lock order check
  Lock #1 (0x....) locked at
     ...
     by 0x4011A0: BankAccount::transfer_from (transfer.cpp:13)
  Lock #2 (0x....) locked at
     ...
     by 0x4011C8: BankAccount::transfer_from (transfer.cpp:14)
  Lock #2 (0x....) previously locked at
     ...
     by 0x401208: main::$_1::operator() (transfer.cpp:44)
  Lock #1 (0x....) previously locked at
     ...
     by 0x401208: main_$_1::operator() (transfer.cpp:44)

  This indicates that the locking order is inconsistent.

Helgrind 明确告诉你：锁的获取顺序不一致。一个路径是先 #1 后 #2（transfer.cpp:13-14），另一个路径是先 #2 后 #1。修复方法是用 std::lock 来同时获取两把锁，它内部使用 try-and-back-off 算法避免了死锁：

cpp

void transfer_from(BankAccount& other, int amount)
{
    // std::lock 同时获取两把锁，避免死锁
    std::lock(mutex_, other.mutex_);
    std::lock_guard<std::mutex> lk1(mutex_, std::adopt_lock);
    std::lock_guard<std::mutex> lk2(other.mutex_, std::adopt_lock);

    if (other.balance_ >= amount) {
        other.balance_ -= amount;
        balance_ += amount;
    }
}

TSan vs Helgrind：怎么选？

这两个工具有不少重叠的功能，但各有侧重。

TSan 是编译期插桩，需要重新编译但运行开销相对较小（虽然也有 5-15x 的 slowdown），对 C++ 标准库的同步原语支持最好，报告格式清晰易读。如果你能重新编译项目，TSan 通常是首选——它对 data race 的检测更精准，假阳性率更低。

Helgrind 是运行时动态分析，不需要重新编译（只要有调试符号），但运行开销比 TSan 更大（通常 20-50x slowdown），因为每条指令都要被 Valgrind 的 IR 翻译一遍。Helgrind 的优势在于你可以直接拿一个已经编译好的二进制来分析，不需要搭编译环境。另外，Helgrind 对锁顺序的分析特别强——如果你怀疑有死锁风险但还没触发过，Helgrind 的锁顺序图能提前帮你发现隐患。

笔者的建议是：日常开发用 TSan，快速检测 data race；当你需要分析锁顺序问题或者无法重新编译时，再上 Helgrind。两者可以互补，不需要二选一。

编译期防线：Clang Thread Safety Analysis

TSan 和 Helgrind 都是运行时工具——你需要先让 bug 发生，它们才能检测到。但有一类问题可以在编译期就防住。Clang 的 Thread Safety Analysis（TSA）是一个编译期的静态分析扩展，通过代码注解来声明线程安全约束，然后编译器会在编译时检查你是否违反了这些约束。零运行时开销，零性能影响——它完全在编译期工作。

基本注解

TSA 的核心概念是"能力"（capability）。一个 mutex 就是一种能力——持有它才能访问被它保护的数据。你需要用宏（底层是 __attribute__）来声明这些约束。

首先，你需要为你的 mutex 类型添加 CAPABILITY 注解：

cpp

// 为标准库 mutex 包装一个带注解的类型
class CAPABILITY("mutex") Mutex {
public:
    void lock() ACQUIRE() { mu_.lock(); }
    void unlock() RELEASE() { mu_.unlock(); }
    bool try_lock() TRY_ACQUIRE(true) { return mu_.try_lock(); }

private:
    std::mutex mu_;
};

// RAII 守卫也需要注解
class SCOPED_CAPABILITY MutexGuard {
public:
    explicit MutexGuard(Mutex& m) ACQUIRE(m) : mu_(m) { mu_.lock(); }
    ~MutexGuard() RELEASE() { mu_.unlock(); }

    MutexGuard(const MutexGuard&) = delete;
    MutexGuard& operator=(const MutexGuard&) = delete;

private:
    Mutex& mu_;
};

然后，你可以用 GUARDED_BY 来声明数据成员被哪个 mutex 保护，用 REQUIRES 来声明函数需要在调用前获取哪个锁：

cpp

class ThreadSafeQueue {
public:
    void push(int value)
    {
        MutexGuard lk(mutex_);   // 获取锁
        data_.push_back(value);  // OK，锁已持有
    }

    int pop()
    {
        MutexGuard lk(mutex_);
        int val = data_.front();  // OK
        data_.pop_front();
        return val;
    }

    // 危险！跳过锁直接读
    int unsafe_front()
    {
        return data_.front();  // 编译警告！
    }

    // 声明需要调用者持有锁
    int front_locked() REQUIRES(mutex_)
    {
        return data_.front();  // OK，调用者保证持锁
    }

private:
    mutable Mutex mutex_;
    std::deque<int> data_ GUARDED_BY(mutex_);
};

用 -Wthread-safety 编译时，unsafe_front() 会触发编译警告，因为在没有持有 mutex_ 的情况下访问了被 GUARDED_BY(mutex_) 保护的 data_。而 front_locked() 加了 REQUIRES(mutex_) 注解，编译器知道它需要调用者持锁，内部访问 data_ 是安全的——如果有人不带锁调用 front_locked()，警告会出现在调用者那边。

锁顺序注解

TSA 还支持声明锁的获取顺序，防止死锁：

cpp

class NetworkManager {
private:
    Mutex stats_mutex_ ACQUIRED_AFTER(data_mutex_);
    Mutex data_mutex_;

    std::vector<int> data_ GUARDED_BY(data_mutex_);
    int total_bytes_ GUARDED_BY(stats_mutex_);
};

如果你在某个地方先锁 data_mutex_ 再锁 stats_mutex_，没问题——这符合声明的顺序。但如果你反过来，先锁 stats_mutex_ 再锁 data_mutex_，编译器就会报警。

启用方式很简单：

bash

clang++ -Wthread-safety -c your_file.cpp

⚠️ 注意：TSA 是纯静态分析，它不能替代运行时工具。它只能检查你加了注解的约束，对于没有注解的代码它完全不管。而且 TSA 目前是 Clang 独有的扩展，GCC 和 MSVC 不支持。但如果你用 Clang 构建，在关键数据结构上加注解、让编译器帮你把关，能省掉大量调试时间。

死锁的运行时诊断

TSA 可以在编译期预防部分死锁，但如果你的程序已经卡死了，你需要运行时的诊断手段。

GDB：最直接的手段

当程序死锁时，最直接的做法是用 GDB 附加到进程上，查看所有线程的调用栈：

bash

# 找到你的进程 PID
ps aux | grep your_program

# GDB 附加
gdb -p <PID>

# 在 GDB 中：查看所有线程的调用栈
(gdb) thread apply all bt

你会看到类似这样的输出：

text

Thread 3 (Thread 0x7f... "your_program"):
#0  __lll_lock_wait (futex=..., private=0) at lowlevellock.c:52
#1  __pthread_mutex_lock (mutex=...) at pthread_mutex_lock.c:67
#2  BankAccount::transfer_from (this=..., other=..., amount=1) at transfer.cpp:13
#3  ...

Thread 2 (Thread 0x7f... "your_program"):
#0  __lll_lock_wait (futex=..., private=0) at lowlevellock.c:52
#1  __pthread_mutex_lock (mutex=...) at pthread_mutex_lock.c:67
#2  BankAccount::transfer_from (this=..., other=..., amount=1) at transfer.cpp:13
#3  ...

两个线程都卡在 __lll_lock_wait（也就是 mutex 的内核等待），而且都在 transfer_from 的第 13 行——这就是死锁的铁证。根据调用栈你可以推断出锁的获取顺序，然后修复它。

GDB 的 Python 脚本辅助

对于复杂项目，纯手看 thread apply all bt 的输出很累。你可以写一个简单的 GDB Python 脚本来提取所有等待锁的线程和它们等待的 mutex 地址：

python

# save as deadlock_detector.py
import gdb

class DeadlockDetector(gdb.Command):
    """Detect potential deadlocks by showing all threads waiting on mutexes."""

    def __init__(self):
        super().__init__("detect-deadlock", gdb.COMMAND_USER)

    def invoke(self, arg, from_tty):
        threads = gdb.selected_inferior().threads()
        for thread in threads:
            thread.switch()
            frame = gdb.selected_frame()
            sal = frame.find_sal()
            try:
                # 尝试找到 __lll_lock_wait 或 pthread_mutex_lock
                func_name = frame.function().name or ""
                if "lock" in func_name.lower():
                    print(f"Thread {thread.num} waiting on lock at "
                          f"{sal.symtab.filename}:{sal.line}")
            except Exception:
                pass

DeadlockDetector()

在 GDB 里 source deadlock_detector.py 后，直接输入 detect-deadlock 就能看到所有在等锁的线程。

结构化日志：让 printf 靠谱一点

调试并发程序时，很多人的第一反应是加 printf 或者 std::cout。这有两个严重的问题。

第一，printf 和 std::cout 本身不是线程安全的（确切地说，C++ 标准保证它们不会导致数据竞争，但多个线程同时写入 std::cout 时输出会交错混乱）。你加了一堆 print，看到的输出可能是一行被另一个线程的输出截断的乱码——比没有日志还糟糕。

第二，没有时间戳和线程标识的日志几乎没用。当你看到两行输出 value = 42 和 value = 0 时，你完全不知道是哪个线程在什么时候写的，也不知道它们的先后顺序。

一个最小化的 thread-safe logger

我们需要的是一个线程安全的、每条日志带时间戳和线程 ID 的 logger。下面这个实现虽然简单但实用：

cpp

#include <mutex>
#include <chrono>
#include <sstream>
#include <iostream>
#include <thread>
#include <iomanip>
#include <atomic>

class ThreadSafeLogger {
public:
    static ThreadSafeLogger& instance()
    {
        static ThreadSafeLogger logger;
        return logger;
    }

    void log(const std::string& level, const std::string& message)
    {
        auto now = std::chrono::steady_clock::now();
        auto ns = std::chrono::duration_cast<std::chrono::nanoseconds>(
            now.time_since_epoch());

        // 先在局部构建完整的日志行，再一次性加锁输出
        // 这样锁的持有时间最短
        std::ostringstream oss;
        oss << "[" << std::setw(16) << ns.count() << " ns] "
            << "[" << std::this_thread::get_id() << "] "
            << "[" << level << "] "
            << message << "\n";

        std::lock_guard<std::mutex> lk(mutex_);
        std::cout << oss.str();
    }

private:
    ThreadSafeLogger() = default;
    std::mutex mutex_;
};

// 便捷宏，减少打字量
#define LOG_INFO(msg)  ThreadSafeLogger::instance().log("INFO", msg)
#define LOG_WARN(msg)  ThreadSafeLogger::instance().log("WARN", msg)
#define LOG_ERROR(msg) ThreadSafeLogger::instance().log("ERROR", msg)

关键的实现细节在于：我们先在局部用 std::ostringstream 构建完整的日志行，然后再加锁输出。这样做的好处是锁的持有时间非常短（只有一次 std::cout << string），减少了锁竞争。如果你在锁内做格式化，多个线程就会排队等格式化完成，这对并发性能的影响是不可忽略的。

每条日志包含三个关键信息：纳秒级时间戳（用于确定事件顺序）、线程 ID（用于区分不同线程的行为）、以及日志级别。有了这些信息，你在分析并发 bug 时就可以精确地追踪每个线程的时间线。

使用起来很简单：

cpp

ThreadSafeLogger::instance().log("INFO",
    "Acquired mutex for account " + std::to_string(account_id));

输出形如：

text

[  123456789012345 ns] [140234567890] [INFO] Acquired mutex for account 42
[  123456789045678 ns] [140234567891] [INFO] Acquired mutex for account 17

从时间戳和线程 ID 你可以清楚地看到，两个线程几乎同时获取了不同的 mutex——如果它们在后续以相反顺序获取第二个 mutex，你就找到了死锁的根因。

⚠️ 注意：这个 logger 用 std::cout 作为底层输出，如果你的程序需要高性能日志（比如每秒数百万条），这个实现不够用——你需要换成无锁的 ring buffer 方案或者用现成的日志库（spdlog 等）。但调试阶段它完全够用了。

系统性诊断流程

好，到这里我们已经介绍了四种主要工具——TSan、Helgrind、Clang TSA 和结构化日志。问题是，当你在实际项目中遇到一个并发 bug 时，应该按照什么顺序来使用这些工具？笔者根据自己的踩坑经验，总结了一套流程。

当你发现一个疑似并发 bug 时，第一步永远是尽可能稳定地复现它。这是最难也是最关键的一步。你需要记录触发 bug 的所有条件：输入数据、线程数量、系统负载、甚至硬件型号。如果 bug 只在高并发时出现，就写一个压力测试反复跑；如果只在特定数据下出现，就保留那份数据。一个不能稳定复现的 bug 几乎不可能被修复——因为你无法验证你的修复是否有效。如果确实无法稳定复现，考虑在 CI 里加一个循环测试——同一个测试跑 1000 次，只要有一次失败就算挂。

复现之后，第二步是确定 bug 的类别。是数据竞争、死锁、活锁还是悬挂引用？如果是程序输出了错误的结果但是没有崩溃，大概率是数据竞争。如果是程序卡死不动，可能是死锁。如果是 CPU 100% 但没有输出，可能是活锁。如果是 segfault 而且栈追踪里出现了奇怪的地址，可能是悬挂引用。这个分类决定了你接下来用什么工具。

第三步，选择并运行工具。如果是数据竞争，编译一个 TSan 版本跑一遍。如果是死锁风险，用 Helgrind 的锁顺序分析。如果是已经死锁的进程，用 GDB 附加查看所有线程栈。如果是悬挂引用，ASan 会更合适（虽然这一篇我们主要讲并发工具，但 ASan 对 use-after-free 的检测非常精准）。

第四步，分析工具的报告。TSan 的报告会精确告诉你哪一行代码有问题、哪些线程在冲突。Helgrind 会告诉你锁的获取顺序哪里不一致。GDB 会告诉你每个线程卡在哪里。仔细读报告——不要急于修改代码，先确保你理解了问题的根因。

第五步，修复并验证。修复之后，重新跑 TSan/Helgrind 确认报告消失，重新跑你的复现测试确认 bug 不再出现。如果有条件，在 CI 里加上 TSan 构建作为常驻检查，防止同类问题再次引入。

这个流程看起来简单，但每一步都有坑。最常见的错误是跳过"复现"直接去读代码猜 bug 位置——在并发程序中，你猜的位置大概率是错的，因为并发 bug 的根因往往在看似毫不相关的代码路径上。另一个常见错误是修复后不跑 TSan 验证——你以为修好了，但实际上你可能只是改变了时序让 bug 更少出现，而不是从根本上消除了它。

我们的位置

这一篇我们建立了一套并发调试的工具箱和方法论。TSan 通过编译期插桩在运行时捕获数据竞争，Helgrind 通过动态分析检测锁顺序问题和竞争，Clang TSA 在编译期用注解预防线程安全违规，GDB 在程序死锁时提供现场快照，而结构化日志帮我们在调试阶段追踪事件的时间线。这些工具各有侧重，组合使用能覆盖绝大多数并发 bug 场景。

但"正确"只是并发编程的一半。一个没有 bug 的并发程序不等于一个高效的并发程序——你可能花了一周时间优化一个 mutex，结果发现瓶颈根本不在这里；也可能为了追求无锁性能引入了复杂到无法维护的代码。下一篇我们要讨论的是如何科学地测量并发程序的性能：Google Benchmark 的多线程用法、并发 benchmark 设计中的常见陷阱、perf 工具的性能计数器分析。调试告诉我们"哪里错了"，基准测试告诉我们"哪里慢了"——两者结合，才是完整的并发工程能力。

💡 完整示例代码在 Tutorial_AwesomeModernCPP，访问 code/volumn_codes/vol5/ch08-debug-testing-perf/。

参考资源

ThreadSanitizer — LLVM Documentation — TSan 官方文档，涵盖用法、限制和配置选项
Dynamic Race Detection with LLVM Compiler — Google Research — TSan-LLVM 的原始论文，详细描述混合检测算法
Helgrind: an experimental thread error detector — Valgrind Manual — Helgrind 官方手册，包含锁顺序分析和注解 API
Thread Safety Analysis — Clang Documentation — Clang TSA 的完整参考，包含所有注解的用法
Thread Safety Analysis in C and C++ — CERT/SEI (CMU) — TSA 背后的设计理念和工业应用
C/C++ Thread Safety Analysis — Google Research (PDF) — TSA 的原始论文，Hutchins 等人著

并发程序调试技巧 ​

环境说明 ​

并发 bug 的四大门派 ​

ThreadSanitizer：数据竞争的克星 ​

原理：编译器插桩 ​

启用 TSan ​

实战：一个 data race 的完整诊断 ​

TSan 的局限 ​

Helgrind：Valgrind 的线程错误检测 ​

原理与使用 ​

实战：锁顺序错误 ​

TSan vs Helgrind：怎么选？ ​

编译期防线：Clang Thread Safety Analysis ​

基本注解 ​

锁顺序注解 ​

死锁的运行时诊断 ​

GDB：最直接的手段 ​

GDB 的 Python 脚本辅助 ​

结构化日志：让 printf 靠谱一点 ​

一个最小化的 thread-safe logger ​

系统性诊断流程 ​

我们的位置 ​

参考资源 ​

并发程序调试技巧

环境说明

并发 bug 的四大门派

ThreadSanitizer：数据竞争的克星

原理：编译器插桩

启用 TSan

实战：一个 data race 的完整诊断

TSan 的局限

Helgrind：Valgrind 的线程错误检测

原理与使用

实战：锁顺序错误

TSan vs Helgrind：怎么选？

编译期防线：Clang Thread Safety Analysis

基本注解

锁顺序注解

死锁的运行时诊断

GDB：最直接的手段

GDB 的 Python 脚本辅助

结构化日志：让 printf 靠谱一点

一个最小化的 thread-safe logger

系统性诊断流程

我们的位置

参考资源