Go runtime.AddCleanup 怎样注册对象清理回调

如果一个 Go 对象只是包装文件描述符、句柄或其他外部资源，想在对象变得不可达后补做一次释放，可以使用 Go 1.24 引入的 runtime.AddCleanup。它适合做兜底清理，但不应替代业务代码里的显式 Close：回调由垃圾回收器决定何时入队，程序退出前也不保证一定执行。

最稳妥的写法是：让 ptr 指向包装对象，让 arg 只携带真正要释放的资源状态，回调函数不要闭包捕获包装对象；正常路径显式关闭，清理回调只负责兜底。

一次资源泄漏复盘：对象没了，句柄还在

故障通常表现为业务对象数量已经下降，但文件描述符、原生句柄或其他外部资源仍在增长。排查时容易把责任归到 GC “没有及时回收”，但真正的问题往往是：对象回收和资源释放不是同一个时刻，而程序又没有为包装类型设计一个清晰的关闭路径。

在 Go 1.24 之前，很多代码会用 runtime.SetFinalizer 补救这类场景。现在新代码更适合先考虑 AddCleanup。它允许同一个对象挂载多个 cleanup，也不会像旧 finalizer 那样普遍延迟被引用对象的释放；但它仍然是运行时兜底机制，不是确定性的生命周期管理器。

先看清 AddCleanup 的三个参数

函数签名是 runtime.AddCleanup[T, S any](ptr *T, cleanup func(S), arg S) runtime.Cleanup。三个参数的职责最好分开理解：

对象变得不可达后，运行时会在稍后的时间、通过独立 goroutine 调用 cleanup(arg)。多个 cleanup 没有规定的执行顺序，也可能彼此并发，所以回调要短小、可并发，并且不能依赖另一个 cleanup 先完成。

把清理状态从包装对象里拆出来

下面的示例模拟一个拥有外部文件描述符的对象。关键点是 cleanupState 不保存 *Resource，这样回调拿到状态时不会把被观察对象重新拉回可达图。

package main

import (
    "fmt"
    "runtime"
    "sync"
)

// cleanupState 只保存释放所需的数据，不反向引用 Resource。
type cleanupState struct {
    once sync.Once
    fd   int
}

// release 可能由显式 Close 或 runtime.AddCleanup 调用，因此必须幂等。
func release(state *cleanupState) {
    state.once.Do(func() {
        // 这里替换成真实的 close、释放句柄或 C API 调用。
        fmt.Println("release fd:", state.fd)
    })
}

type Resource struct {
    state   *cleanupState
    cleanup runtime.Cleanup
}

func NewResource(fd int) *Resource {
    state := &cleanupState{fd: fd}
    resource := &Resource{state: state}
    // cleanup 的参数独立于 resource，避免形成 ptr -> arg -> ptr 的引用链。
    resource.cleanup = runtime.AddCleanup(resource, release, state)
    return resource
}

func (r *Resource) Close() {
    if r == nil {
        return
    }
    // Stop 只取消尚未入队的 cleanup；release 的 Once 负责处理竞态。
    r.cleanup.Stop()
    release(r.state)
}

这里返回的 runtime.Cleanup 句柄保存在包装对象里，便于正常关闭时调用 Stop。即使 cleanup 已经入队，Stop 也可能来不及取消，因此 release 用 sync.Once 保证显式关闭和兜底回调最多真正释放一次。

对象什么时候仍然算“可达”

最常见的误判是把“函数快结束了”当作“对象已经可以回收”。编译器可能在最后一次使用对象之后就认为它不再需要。若外部调用必须持续到某个操作完成，应在最后一次操作后调用 runtime.KeepAlive，明确把对象保持到指定位置。

func (r *Resource) Use() {
    if r == nil {
        return
    }
    // 通过 state 使用外部资源；真实项目中这里应检查底层调用的错误。
    fmt.Println("use fd:", r.state.fd)
    // 确保上面的资源操作完成后，Resource 仍保持可达。
    runtime.KeepAlive(r)
}

KeepAlive 不是让对象永久存活，也不会强制 cleanup 立即执行；它只是把可达性边界延后到调用点。反过来，若对象被全局变量、长生命周期缓存或某个 goroutine 持有，cleanup 就不会因为局部函数返回而触发。

四个边界决定它能不能放进生产代码

• 不保证进程退出前执行。短命命令行程序不能靠 cleanup 把最后一个缓冲区写入磁盘；退出前需要显式 flush 和 close。
• 回调没有固定顺序。如果两个对象的释放存在先后依赖，应由显式生命周期管理表达，不能依赖 GC 的入队顺序。
• 回调与业务 goroutine 并发。不要在 cleanup 中访问已经被其他 goroutine 关闭的共享状态；需要共享状态时使用锁或幂等原语，并尽量让回调快速返回。
• 不要让回调或参数引用 ptr。闭包捕获包装对象、把包装对象塞进参数、或者让参数对象反向指回包装对象，都会让清理条件失效；其中一些简单情形会直接 panic。

另外，零大小类型的对象、包级变量初始化阶段创建的对象，以及某些特殊分配场景都不适合拿来推断 cleanup 一定执行。实际资源释放仍应优先由拥有者明确控制。

落地前的清理回调清单

可以把 AddCleanup 当成资源包装类型的最后一道保险，而不是关闭协议本身。写完后逐项检查：

1. 项目编译版本至少为 Go 1.24，且代码确实需要 GC 兜底，而不是可以直接使用 defer 或显式 Close。
2. ptr 是包装对象，arg 只携带释放资源所需的数据，回调闭包不捕获包装对象。
3. 显式关闭路径先取消尚未入队的 cleanup，再用 sync.Once 或等价手段保证与回调并发时不会重复释放。
4. 资源操作的最后一个使用点之后安排 runtime.KeepAlive，避免过早进入不可达状态。
5. 不把 cleanup 的执行时间、执行顺序和进程退出前执行当作业务逻辑依赖。

一句话总结：runtime.AddCleanup 解决的是“对象被 GC 回收后如何补做资源清理”，而不是“资源什么时候必须关闭”。把确定性的关闭动作留给显式 API，再用不反向持有对象的 cleanup 做兜底，边界才清楚。

相关问题

AddCleanup 能完全替代 SetFinalizer 吗？

新代码通常应优先考虑 AddCleanup，但是否迁移仍要检查现有 finalizer 的生命周期假设、并发行为和显式关闭路径。它不是把所有旧代码机械替换成新函数。

为什么调用 runtime.GC 后不能保证马上看到清理结果？

GC 只会让不可达对象具备进入 cleanup 队列的条件，回调还要由运行时异步调度；而且文档明确不保证在程序退出前运行。

Cleanup.Stop 调用后还要释放资源吗？

要。Stop 只负责取消尚未入队的 cleanup，不等价于释放外部资源，所以显式 Close 仍需要执行真正的 release。