Go runtime.AddCleanup 怎样判断输入是否满足边界

判断 runtime.AddCleanup 的输入是否合格，不能只检查 ptr 非 nil。还要保证清理函数和 arg 的引用关系不会把 ptr 保持可达，并让真实使用期间的对象存活、并发清理和显式关闭遵守同一套资源协议。最稳妥的做法是通过受控构造器生成参数：包装对象作为 ptr，独立清理状态作为 arg，顶层函数负责清理，正常路径继续显式 Close。

AddCleanup 不是带时限的释放器，也不提供“参数检查成功便一定回调”的保证。下面用模拟资源计数解释边界，所有数量都是从示例代码推导，没有实际运行或性能测试数据。

官方接口：https://pkg.go.dev/runtime#AddCleanup

官方说明：https://go.dev/blog/cleanups-and-weak

版本说明：https://go.dev/doc/go1.24

1. 基线数据：注册三次，不代表清理回调完成三次

先给指标定名字。示例创建三个 Lease，每个注册一次兜底清理；正常路径对每个 Lease 调用两次 Close，因此一共有六次关闭调用。幂等释放动作的预期完成次数是三次，不能把六次 Close、三次注册和三次真正释放混成一个计数。

这个基线只讨论正常路径的逻辑。它没有等待 GC，也没有观察到自动清理。对泄漏场景来说，包装对象变为不可达后，回调何时运行、是否赶得及进程退出，都不是注册成功时能承诺的结果。

2. 假设：应检查引用图，而不是只比两个地址

Go 1.24 引入 AddCleanup。当前官方文档明确指出：若从 cleanup 或 arg 能到达 ptr，清理就无法按预期发生；arg 直接等于 ptr 的简单情况会触发 panic。不要依赖运行时一定能找出所有间接引用，尤其不要把闭包捕获、状态对象的反向字段和全局引用遗漏掉。

因此，示例让 Lease 指向 releaseState，而 releaseState 只持有幂等状态和计数器，不保存 Lease。cleanup 使用顶层函数 release，没有捕获包装对象。检查重点是清理端不存在反向路径，而不是要求整个程序中没人引用 Lease；真实使用者当然需要在使用期间持有它。

输入还要来自合法的 Go 对象使用方式。nil 指针不能作为有效注册目标，本文不通过 unsafe 伪造指针，也不把零尺寸对象或包级初始化对象当作可靠的清理触发器。官方文档还列出某些微小对象分配合并情况下的回调不保证，不能用“对象已经不用了”推出“回调必然到达”。

3. 改动点：受控构造器与幂等释放

以下原创示例要求 Go 1.24 或以上版本。它只模拟资源释放次数，不会创建文件、关闭句柄或调用外部系统。构造器拒绝 nil 计数器，并固定清理函数和状态形状；它不是一个能检查任意闭包引用图的通用验证器。

package main

import (
    "fmt"
    "runtime"
    "sync"
    "sync/atomic"
)

type releaseState struct {
    once  sync.Once
    count *atomic.Int64
}

func release(s *releaseState) {
    // 这里只模拟资源释放计数，不操作文件或操作系统句柄。
    s.once.Do(func() { s.count.Add(1) })
}

type Lease struct {
    state   *releaseState
    cleanup runtime.Cleanup
}

func NewLease(counter *atomic.Int64) (*Lease, error) {
    if counter == nil {
        return nil, fmt.Errorf("释放计数器不能为空")
    }
    state := &releaseState{count: counter}
    lease := &Lease{state: state}
    // 顶层函数不捕获 lease，state 也不包含指回 lease 的字段。
    lease.cleanup = runtime.AddCleanup(lease, release, state)
    return lease, nil
}

func (lease *Lease) Close() error {
    if lease == nil || lease.state == nil {
        return fmt.Errorf("租约未初始化")
    }
    // Stop 取消待触发清理；真正释放仍要显式执行。
    lease.cleanup.Stop()
    release(lease.state)
    runtime.KeepAlive(lease) // 保持包装对象跨过 Stop 与显式释放。
    return nil
}

func main() {
    var released atomic.Int64
    for i := 0; i 

Close 先取消兜底清理，再显式调用 release。Stop 不是释放资源的动作，也不是等待已经排队回调结束的接口，所以不能只调用 Stop 就宣称资源已经处理。这里的 sync.Once 让两条释放路径遵循同一份幂等协议；原子计数使模拟计数本身可并发更新。

KeepAlive 放在 Stop 和显式释放之后，使包装对象跨过这段必须存活的区间。别把源码作用域理解为保证存活到函数结尾。真实资源若还有 Read、Write 等使用方法，必须把存活区间和 Close 的并发规则一起设计，而不是只保护注册函数。

本例没有提供使用资源的方法，不能据此声称支持“边使用边Close”。如果把模拟计数换成可能失败的关闭调用，还要规定错误保存和重试语义；sync.Once 会限制执行次数，不会自动处理失败重试。

4. 测量方法：释放计数与清理延迟分开

评估真实代码时，至少分别记录对象创建数、Close 调用数、实际释放完成数，以及仅靠兜底路径处理的数量。测量开销时要包含注册、状态对象、同步与正常关闭；不要只测一行 AddCleanup，就把结果当作整个资源生命周期成本。

延迟观察与性能基准也应分开。若要观察自动清理，需要有界的等待和同步机制，并将“等待窗口内没看到”记为未观察到，不能直接判成泄漏，也不能无限等待。强制 GC 完成不等于所有异步清理已执行完毕。本文没有运行这类测量。

5. 结果对比：能推导的是正常关闭合同

“模拟释放次数: 3”只是程序的预期输出，不是本机日志。这个例子选择显式关闭来获得确定性，不用进程退出前睡一小段时间来伪装清理保证。

6. 边界条件：输入合法仍不等于适合该资源

清理可能与业务 goroutine 以及其他清理并发运行，且没有相互顺序保证。需要严格释放顺序的关联资源，不能简单各注册一个 cleanup 再假定谁先执行。必须在自己的所有权与同步设计里表达依赖。

对连接数、文件描述符等有硬上限的资源，正常路径依然应及时显式关闭。AddCleanup 更适合作为遗漏关闭的兜底，不能替代作用域内的释放，也不负责事务提交或关键数据落盘。

只判断 ptr 与 arg 不相等就足够吗？

不够。arg 的字段和闭包环境仍可能间接持有 ptr。应通过简单清晰的结构控制引用关系，而不是泛化一个地址比较函数。

cleanup 能写成包装对象的方法值吗？

要警惕方法值捕获接收者，使清理函数反过来持有注册对象。此处采用顶层函数和独立状态，是为了让引用关系更直接。

Stop 会等待已开始的清理完成吗？

不能这样理解；官方说明其对已经排队的调用可能没有效果。需要协调显式关闭与兜底清理时，应共享幂等状态或其他资源协议，并保持对象跨越必要的存活区间。