TSan 数据竞争报告两段栈怎么读?
更新时间:2026-10-07。短答页。ThreadSanitizer(线程消毒器,下称 TSan,Clang/GCC 内置的动态数据竞争检测器)报
WARNING: ThreadSanitizer: data race时,报告里两段栈一段是「当前发生的访问」、一段是「之前发生、且与之没有同步关系的访问」,读懂这两段 + happens-before 边就能定位竞争。
一句话回答
报告里 Write of size 4 at ... by thread T1 是正在发生的访问,Previous write of size 4 ... by thread T2 是历史上同一地址、未与当前访问建立 happens-before 的访问;两段栈的交点就是共享变量,给这个变量补上互斥锁、原子操作或正确的线程同步(join/信号量),报告即消失。TSan 工具本身的使用见 TSan 线程消毒器。
现象:一段典型的报告长什么样
WARNING: ThreadSanitizer: data race (pid=12345)
Write of size 4 at 0x7b0400000000 by thread T1:
#0 Worker(void*) app.cpp:42
#1 <null> <null>
Previous read of size 4 at 0x7b0400000000 by thread T2:
#0 Logger(void*) app.cpp:58
Location is heap block of size 64 at 0x7b0400000000 allocated by main thread:
#0 malloc
#1 main app.cpp:80
Thread T1 (tid=12347, running) created by main thread at:
#0 pthread_create
#1 main app.cpp:78关键字段只有四个:
- Write/Read of size N at 0x...:当前访问的类型(读还是写)、宽度、地址。地址在两段里必须相同,否则不是同一个竞争。
- Previous read/write ... by thread T?:之前那次访问。TSan 只在「两次访问至少一个写、且互相之间没有 happens-before 边」时才报警。
- Location is ...:这块内存是堆、栈还是全局变量,由谁分配——帮你确认共享变量是哪一个。
- Thread T? created by ...:线程是谁创建的,方便对上业务角色。
原因分类:为什么这两次访问会被判竞争
TSan 的判定核心是 happens-before(先行发生关系:若访问 A happens-before 访问 B,则 B 能看到 A 的写入,两者不构成竞争)。它维护两类同步边:
- 锁边:同一把互斥锁的 unlock → 后续 lock。
- 生命周期边:
pthread_create(创建点 happens-before 新线程体内一切)与pthread_join(被 join 线程的一切 happens-before join 返回点);信号量 post/wait、C++11 原子变量的 release/acquire 也算。
两次对同一地址的访问、至少一个是写、且两条边都连不上,就报警。下面这张图把竞争时序画了出来:

图的读法:pthread_create 在 main 与 T1、main 与 T2 之间各建立一条 happens-before 边,所以 main 在创建前对 counter 的初始化不会和子线程竞争;但 T1 的写与 T2 的读横向没有任何同步边——既没锁、也没 join、也不是原子变量——这就是报告里两段栈对应的两次访问。如果 T2 在读之前先对同一把锁 lock(T1 写完 unlock),或 main 先 join T1 再让 T2 读,这条横向边就补上了,TSan 不再报警。
排查命令与步骤
- 复现编译:
-fsanitize=thread -g -O1(Clang 或 GCC 均可;-g必须,否则栈里没行号)。运行时不必加参数,命中即打报告。 - 先对地址:确认两段栈的
at 0x...一致,再看Location is段找出共享变量的源码名字。 - 对业务角色:用
Thread T? created by段把 T1/T2 映射到业务线程(创建点在哪段代码,谁就是谁)。 - 查同步边:问自己「这两次访问之间有没有锁/原子/join?」——答案是否,就是真竞争。
- 压制噪音(确有误判时):
TSAN_OPTIONS="suppressions=tsan.supp",文件里写race:函数名。
clang++ -fsanitize=thread -g -O1 app.cpp -o app
TSAN_OPTIONS="halt_on_error=1 history_size=7" ./apphistory_size=7 保留更长的访问历史,偶发竞争更容易被抓到;halt_on_error=1 命中即停,方便用 gdb 现场查看。
解决:按共享变量的用途选修法
- 计数/标志位:改
std::atomic<int>,默认顺序一致语义足够;只是统计可放宽到memory_order_relaxed。 - 复杂结构共享:加
pthread_mutex_t或std::mutex,读写两侧都进临界区,TSan 的锁边随之建立。 - 一次性结果传递:用 join、条件变量或信号量建立显式同步边,别靠
sleep赌时序——sleep 不产生 happens-before。 - 实在改不动:
__attribute__((no_sanitize_thread))标注单函数,或在 suppressions 文件压制,但这是最后手段。
常见误报与处理
TSan 误报率低,但有三类典型「看起来像误报」:
- 自己实现的无锁队列/自旋锁:TSan 不认汇编或 compiler barrier,要用
__tsan_acquire(ptr)/__tsan_release(ptr)注解告诉它同步边在哪。 - 第三方库内部竞争:确认与你无关就进 suppressions。
- 双重检查加锁(double-checked locking)写错:标志位不是原子变量,TSan 会忠实地报出来——这是真 bug,不是误报。
内存类问题(越界、泄漏)请转 ASan 地址消毒器 与 Valgrind 使用指南,它们与 TSan 不能同开,要分两遍跑。
防复发
- CI 里加一条 TSan 构建跑核心并发用例,竞争类 bug 在合入前拦截。
- 新增共享变量时先问「谁写谁读、同步边在哪」,把答案写进注释。
- 代码评审把「裸全局变量 + 多线程」列为高亮项。
总结
读 TSan 数据竞争报告只要四步:对地址确认两次访问指向同一变量,用 Location is 找出变量源码,用 created by 对上线程角色,再检查两次访问之间有没有锁/原子/join 建立的 happens-before 边——没有就是真竞争,按用途补原子、互斥锁或显式同步即可消报,自制无锁结构则用 __tsan_acquire/release 注解补齐同步边。