runtime.SetFinalizer 触发不及时时的设计替代

如果 runtime.SetFinalizer 很久没有触发，通常不是垃圾回收“失灵”，而是把一个本来就不确定的兜底机制误当成了确定性的资源释放通知。Go wrapper 持有文件描述符、C 句柄或其他外部资源时，主路径应由显式 Close 完成；finalizer 或 cleanup 只负责降低遗漏关闭的代价。

更稳妥的分工是：显式 Close 负责确定性，runtime.AddCleanup 或 SetFinalizer 负责兜底，runtime.KeepAlive 负责把对象保护到最后一次调用返回。 三者解决的是不同问题，不能互相替代。

先判断 finalizer 为什么会显得不及时

runtime.SetFinalizer 只有在对象变得不可达后，运行时才会把 finalizer 排入执行队列。它没有固定延迟，也不保证在进程退出前运行；对象仍被全局变量、闭包、缓存或其他对象引用时，GC 就不会认为它已经可以清理。

因此，下面几种期待都不成立：

• 调用 runtime.GC() 后，finalizer 一定立刻完成；
• 进程退出前，所有外部句柄一定会由 finalizer 关闭；
• 多个对象的 finalizer 会自动遵循 C 库或业务的父子释放顺序；
• 把 runtime.KeepAlive 加到代码中，就能替代资源所有权管理。

第一层替代：让显式 Close 成为唯一主路径

只要资源需要在请求结束、事务提交或服务退出时按确定顺序释放，就应该提供显式 Close。实现重点不是“关闭函数只能调用一次”，而是让所有释放路径竞争同一个所有权状态：谁先把句柄摘走，谁才有资格调用底层释放函数。

type Handle struct {
    mu  sync.Mutex
    raw unsafe.Pointer
}

func (h *Handle) Close() error {
    h.mu.Lock()
    raw := h.raw
    // 先摘走句柄，保证重复 Close 与兜底清理不会拿到同一资源。
    h.raw = nil
    h.mu.Unlock()

    if raw == nil {
        // Close 设计成幂等，调用方可以安全地使用 defer h.Close()。
        return nil
    }

    // 这里调用真实库的释放函数，并保留底层错误映射。
    C.release_handle(raw)
    // 让 h 活到最后一次跨语言调用返回。
    runtime.KeepAlive(h)
    // 主动释放成功后，不再保留 SetFinalizer 兜底入口。
    runtime.SetFinalizer(h, nil)
    return nil
}

如果释放函数可能返回错误，应在摘走句柄后记录状态并返回错误，但不要把句柄重新放回 h.raw，否则 finalizer 和并发 Close 都可能再次抢到同一个资源。需要重试时，应该由底层库提供新的句柄或独立的重试协议。

第二层替代：Go 1.24 以上评估 runtime.AddCleanup

当前 runtime 文档建议新代码考虑 runtime.AddCleanup，因为它把“需要清理的参数”与“被观察的对象”分开了，不必像 SetFinalizer 那样让 finalizer 接收对象本身。它仍然是非确定性的兜底机制：清理函数可能很晚执行，也不保证在程序退出前执行。

AddCleanup 还带来几个必须记住的差异：多个 cleanup 可以绑定到同一个对象；不同对象之间没有规定的执行顺序；cleanup 之间可能并发执行；如果 cleanup 或参数反向引用了被观察对象，可能导致对象始终可达。它适合做独立、幂等、短小的兜底动作，不适合拼接复杂父子资源顺序。

type Resource struct {
    raw unsafe.Pointer
}

func NewResource() (*Resource, error) {
    raw := C.open_handle()
    if raw == nil {
        return nil, errors.New("open_handle failed")
    }

    r := &Resource{raw: raw}
    // 把 C 句柄作为独立参数交给 cleanup，避免 cleanup 反向持有 r。
    runtime.AddCleanup(r, func(p unsafe.Pointer) {
        if p != nil {
            // 兜底动作必须可重复或由所有权协议保证只执行一次。
            C.release_handle(p)
        }
    }, raw)
    return r, nil
}

示例只展示 API 形状。真实封装仍需让显式 Close 与 cleanup 使用同一套一次性所有权协议；如果 cleanup 直接保存一份原始句柄，而 Close 先释放了它，必须确保底层释放函数或 wrapper 状态能防止二次释放。更常见的做法是把资源状态放入一个独立的共享 owner，再让显式路径与兜底路径通过锁或原子状态领取它。

第三层保护：KeepAlive 要放在最后一次使用之后

runtime.KeepAlive(x) 的作用是保证 x 在该调用点之前仍然可达。若 wrapper 的最后一次 Go 层使用发生在系统调用或 cgo 调用入口处，编译器可能认为后续已经不再需要 wrapper；这时 finalizer 有机会在底层调用真正结束前关闭句柄。

func (h *Handle) Read(buf []byte) error {
    if len(buf) == 0 {
        // 空缓冲区不取 buf[0]，按底层 API 的约定处理空输入。
        return nil
    }

    h.mu.Lock()
    raw := h.raw
    h.mu.Unlock()
    if raw == nil {
        return errors.New("handle is closed")
    }

    // C 只在本次调用期间读取 Go 缓冲区，不得把 Go 指针保存到调用之外。
    if rc := C.read_handle(raw, unsafe.Pointer(&buf[0]), C.size_t(len(buf))); rc != 0 {
        // 将底层错误码转换为稳定的 Go 错误，便于调用方处理。
        return fmt.Errorf("read_handle failed: %d", int(rc))
    }
    // 这是最后一次依赖 h 的位置，必须覆盖整个 cgo 调用窗口。
    runtime.KeepAlive(h)
    return nil
}

把 KeepAlive 放在调用前只能保护到调用前的某个位置，不能表达“底层调用已经返回”。它也不会让 C 资源自动续期，更不会修复底层库保存 Go 指针、越界访问或重复释放的问题。

用一个 owner 收拢父子资源和并发关闭

如果一个连接包含会话、回调、缓冲区和父句柄，不要为每一层都设置一个 finalizer，再期待运行时替你推导释放顺序。应该让一个显式 owner 管理状态：先禁止新调用，等待进行中的调用结束，再释放子资源，最后释放父资源。

关闭顺序通常可以写成“停止新请求 → 等待在途调用 → 释放回调和子资源 → 释放父句柄 → 关闭兜底机制”。如果 C 库要求在创建线程上释放，主动 owner 还要承载线程亲和性；不要直接在不合适的 finalizer goroutine 中调用受线程限制的 API。

cgo 指针规则不能靠 finalizer 兜底

runtime.KeepAlive 只延长 Go 对象的可达性，不会把 Go 指针变成 C 可以永久保存的指针。cgo 文档要求：传给 C 的 Go 指针所指向内存必须满足固定规则，C 代码不得在调用返回后保存未固定的 Go 指针；字符串、切片等也不能因为 wrapper 有 finalizer 就被长期保留。

func Send(r *Resource, data []byte) error {
    if len(data) == 0 {
        // 空切片没有可安全取地址的第一个元素，按 API 约定传空指针或直接返回。
        return nil
    }

    raw := r.raw
    if raw == nil {
        return errors.New("resource is closed")
    }

    // C 函数只能在本次调用期间读取 data，不能把该 Go 指针保存起来。
    if rc := C.consume(raw, unsafe.Pointer(&data[0]), C.size_t(len(data))); rc != 0 {
        // 调用方只接收明确错误，不把底层指针暴露到 Go 业务层。
        return fmt.Errorf("consume failed: %d", int(rc))
    }
    // 保证 wrapper 至少活到 consume 返回。
    runtime.KeepAlive(r)
    return nil
}

需要长期保存数据时，应让 C 侧复制到自己的内存，或者使用符合 cgo 规则的句柄传递 Go 值。把 finalizer 加在 wrapper 上并不会改变 C 侧的指针所有权，也不会让非法保存变成合法。

把替代方案落成一张决策表

怎样留下可排查的关闭证据

工程上可以为 wrapper 记录创建数、显式 Close 数、兜底清理数、释放错误数和仍存活的 owner 数。监控重点不是“GC 多久运行一次”，而是“哪一条路径拿到了资源所有权”。兜底清理计数持续上升，通常说明调用方遗漏了显式关闭；释放错误集中出现，则应回到底层 C API 的状态和并发约束。

排查时按这个顺序处理：

1. 确认 wrapper 是否已经进入 Closed，以及句柄是否在关闭时原子地摘走；
2. 确认最后一次系统或 cgo 调用之后是否有 runtime.KeepAlive；
3. 确认 cleanup/finalizer 是否反向引用 wrapper，是否可能与显式关闭并发；
4. 确认父子资源是否由同一个 owner 按明确顺序释放；
5. 确认 C 代码没有在调用结束后保存不允许长期保存的 Go 指针。

常见问题

SetFinalizer 一直不触发，是不是需要频繁调用 runtime.GC？

不应把强制 GC 当作生产清理方案。先检查对象是否仍可达，再把业务需要的释放动作改成显式 Close；即使对象已不可达，finalizer 也只保证“可能被调度”，不保证业务需要的及时性。

AddCleanup 能完全替代 Close 吗？

不能。它同样不保证在退出前执行，而且 cleanup 之间没有规定顺序。它适合独立、幂等的兜底释放，确定性的资源交接仍应由显式 Close 完成。

SetFinalizer 和 AddCleanup 应该选哪个？

新代码可优先评估 AddCleanup；需要兼容旧版本或已有 finalizer 设计时可以继续使用 SetFinalizer，但要保留显式 Close、幂等状态和 KeepAlive。选择不能改变“兜底不是主路径”这一原则。

KeepAlive 能阻止 C 句柄被关闭吗？

它只保证传入的 Go 对象在指定点前保持可达，不能替代 C 资源的所有权，也不能修复 C 指针保存、越界访问、线程亲和性或 double free 问题。

参考资料

Go runtime 包文档：https://pkg.go.dev/runtime

Go runtime finalizer 源码：https://go.dev/src/runtime/mfinal.go

Go cgo 指针规则：https://pkg.go.dev/cmd/cgo