Golang 中 sync.WaitGroup 内部 64 位状态字段的原子操作-Golang-PHP中文网

WaitGroup.state 用单个 uint64 原子变量同时存储高32位counter和低31位waiter，必须通过原子CAS或Add一次性更新，禁止拆读拆写；Add(n)增计数，Done等价Add(-1)，负值panic；state布局属内部实现，不可直接操作。

WaitGroup.state 是一个 uint64 原子变量，不能拆读拆写

waitgroup 内部只用一个 state 字段（atomic.uint64）就同时存了两个关键状态：高 32 位是任务计数器 counter，低 31 位是等待者数量 waiter（最低 1 位为测试预留，业务无关）。这意味着任何对 counter 或 waiter 的修改，都必须通过单次原子操作完成，否则会破坏状态一致性。

常见错误是试图分别读取高低位再各自更新，比如：

// ❌ 错误：两次独立原子读，中间可能被其他 goroutine 修改
high := atomic.LoadUint64(&wg.state) >> 32
low := atomic.LoadUint64(&wg.state) & 0xffffffff
// 然后想改 high 或 low —— 已失效

正确做法是用 atomic.CompareAndSwapUint64 或 atomic.AddUint64 一次性更新整个 64 位，让 runtime 保证高低位同步生效。

Add 和 Done 都在改高 32 位 counter，但 Done 是 Add(-1)

wg.Add(n) 本质是原子地给 counter 加 n；wg.Done() 就是 wg.Add(-1)。只要 counter 变成负数，就会 panic：sync: WaitGroup misuse: negative WaitGroup counter。

典型踩坑：在 goroutine 启动前没调 wg.Add(1)，或重复调用 Done()
注意：Add 的参数可以是任意整数，但 runtime 只检查最终结果是否
如果并发调 Add 和 Wait（比如 Add 在 Wait 执行中被调），也可能触发 sync: WaitGroup misuse: Add called concurrently with Wait panic

Wait() 如何靠低 32 位 waiter 实现阻塞唤醒

当 wg.Wait() 发现 counter > 0，它会尝试把低 32 位的 waiter +1，并进入阻塞。这个 +1 操作本身也是原子的，且和判断 counter == 0 绑定在同一个 CAS 中 —— 如果刚好此时另一个 goroutine 执行了最后一个 Done() 让 counter 归零，那 Wait() 就直接返回，不进等待队列。

唤醒逻辑由 Go runtime 控制：sema 是一个普通 uint32，不参与原子状态，只作为信号量标识。当 counter 归零时，runtime 会批量唤醒所有登记在 waiter 数量内的 goroutine。

Golang Naming

Go（Golang）命名规范 — 包括包、构造函数、结构体、接口、常量、枚举、错误、布尔值、接收器、getter/setter、函数等。

下载

这意味着：多个 Wait() 可以同时阻塞，但只要有一个 Done() 把 counter 推到 0，所有等待者都会被唤醒 —— 不是“一对一”唤醒。

为什么不能混用 atomic 包直接操作 WaitGroup.state

WaitGroup.state 是未导出字段，Go 标准库不承诺其布局稳定。虽然当前版本是高 32 位 counter + 低 32 位 waiter，但这是实现细节，不是 API 合约。手动解析 state 值、用 atomic 函数绕过 Add/Done/Wait，等于在依赖内部内存布局。

实际风险包括：