Go Cleanup.Stop 为什么没有取消已经排队的清理函数

我第一次把 runtime.AddCleanup 接到一个临时资源包装对象上时，最容易误解的是 Cleanup.Stop 的“取消”范围：它不是把已经进入运行队列的清理函数追回来，而是尝试移除仍挂在对象上的清理记录。对象一旦因为不可达而让清理函数排队，随后再调用 Stop 就不会改变结果。

要保证 Stop 真能取消清理，关键不是把调用写得更快，而是让传给 AddCleanup 的那个指针在整个 Stop 调用期间保持可达。对象若已经不可达，清理可能已经排队；此时应把它当成不可撤销的异步工作处理。

先看清 Cleanup.Stop 能取消什么

Cleanup 是 Go 运行时为某个对象保存的清理句柄。AddCleanup 绑定的是“对象不可达后，稍后在独立 goroutine 中调用清理函数”的关系，而不是一个普通的定时器。官方文档还特别说明，清理函数的执行时间不确定，也不保证在进程退出前运行。

因此可以把状态简单分成两段：

为什么局部变量会让 Stop 看起来失效

垃圾回收器只关心对象在某个时刻是否仍能从根对象追踪到。函数参数或接收者可能在最后一次被使用之后就被判断为不可达，即使它在源代码的词法作用域里还没有离开。若这时发生 GC，清理记录可能先被放入队列，之后的 Stop 已经错过取消窗口。

下面的写法把“注册清理”和“对象保持可达”混在了一起，不能把 Stop 视为必然生效：

package main

import "runtime"

type Resource struct {
	fd int
}

func release(fd int) {
	// 示例只表达释放动作；真实代码应处理底层资源的错误。
}

func cancelTooLate(r *Resource) {
	cleanup := runtime.AddCleanup(r, release, r.fd)

	// r 后面没有再次被使用，运行时可能在这里认为它已不可达。
	runtime.GC()

	// 如果清理已经排队，Stop 不会把它从队列中追回。
	cleanup.Stop()
}

示例中的 runtime.GC() 只是为了把时序问题讲清楚，生产代码不要用它“催促”清理。真正的问题是 Stop 调用之前，r 是否仍被运行时认为可达。

用 KeepAlive 明确 Stop 前的存活边界

当业务逻辑必须先做一次显式释放，再撤销兜底清理时，可以在 Stop 之后调用 runtime.KeepAlive，把“对象必须活到哪里”写给编译器和读代码的人。这里的顺序很重要：先完成 Stop，再用 KeepAlive 覆盖到该调用点。

func cancelCleanup(r *Resource) {
	cleanup := runtime.AddCleanup(r, release, r.fd)

	// 先执行自己的资源关闭逻辑，避免把清理函数当成同步 Close。
	release(r.fd)

	// KeepAlive 的调用点之后，r 才不再需要保持可达。
	cleanup.Stop()
	runtime.KeepAlive(r)
}

这段代码的意图是让 r 跨过 Stop 仍可达，从而保证运行时还有机会找到并移除对应的清理记录。KeepAlive 不会等待清理执行，也不会让已排队的函数停止；它只声明对象的存活下界。

别让清理函数或 arg 反向抓住 ptr

AddCleanup 的另一个常见坑不是 Stop，而是清理函数本身把对象重新捕获了。例如下面的闭包直接读取 r，运行时检测到清理函数能追到 ptr，对象就不会被回收，清理也不会运行：

func badCleanup(r *Resource) runtime.Cleanup {
	// 不要让闭包捕获 r；这会形成从 cleanup 回到 ptr 的路径。
	return runtime.AddCleanup(r, func(_ int) {
		_ = r.fd
	}, r.fd)
}

正确做法是把清理所需的独立值作为 arg 传入，让闭包不再引用 ptr：

func goodCleanup(r *Resource) runtime.Cleanup {
	fd := r.fd
	return runtime.AddCleanup(r, func(fd int) {
		// 只使用独立的 fd，不回头访问 r。
		release(fd)
	}, fd)
}

同理，arg 也不能等价于 ptr，不能指向 ptr 内部的对象。否则清理关系会把被清理对象重新保活，代码看起来已经注册成功，实际却不会按预期触发。

把 Stop 放在正确的资源生命周期里

我现在会把清理分成“兜底”和“主路径”两层：显式的 Close、Release 或事务提交负责确定性释放，AddCleanup 只负责遗漏时的兜底动作。显式释放完成后，用保持可达的对象调用 Stop，避免兜底函数重复处理同一资源。

需要特别注意三点：

• Stop 不是等待接口，不会等待已排队的清理函数结束。
• 清理函数可能和业务 goroutine 并发执行，也可能和其他清理函数并发执行；共享资源必须自行同步。
• 不要重复对同一个生命周期注册多个清理函数，否则显式释放、多个兜底函数和 Stop 的责任边界会变得不清楚。

最后用一张表排查 Stop 无效

相关问题

Cleanup.Stop 能不能保证清理函数不执行？

不能。只有在清理尚未排队且传给 AddCleanup 的指针在 Stop 调用期间保持可达时，才能保证移除清理记录。

为什么不直接用 defer？

defer 适合确定的函数返回边界，AddCleanup 面向对象不可达后的兜底清理，两者触发条件不同。能用显式释放或 defer 表达的主路径，不应交给 GC 时机。

调用 Stop 后还要 KeepAlive 吗？

如果需要保证传入的对象跨过 Stop 仍可达，应保留 KeepAlive；它描述的是存活边界，不是同步等待。

记住一句话：Stop 取消的是还挂在对象上的清理注册，不是已经进入队列的异步工作。先设计清楚主路径释放，再用 KeepAlive 固定取消窗口，最后检查闭包和 arg 是否反向引用对象，问题通常就能定位。