runtime.SetFinalizer 链接 C 资源时的释放顺序

Go 代码通过 cgo 持有 C 侧句柄、缓冲区或库对象时，释放顺序要先看清一件事：runtime.SetFinalizer 绑定的是 Go wrapper，不是 C 资源本身。工程上应由 Close 主动释放 C 资源，再用 finalizer 作为遗漏关闭时的最后兜底；最后一次 cgo 调用之后还要用 runtime.KeepAlive 固定 wrapper 的存活边界。

一句话概括：显式 Close 负责确定性，finalizer 负责兜底，KeepAlive 负责避免使用期间过早进入兜底路径。 不要把 finalizer 当成定时器，也不要依赖多个 finalizer 的执行先后去拼出 C 库的依赖顺序。

先分清 Go 对象和 C 资源是谁负责

一个常见封装通常有两层生命周期：

• Go wrapper：由 Go 堆管理，垃圾回收器只判断它是否仍然可达。
• C 资源：可能来自 malloc、C 库的创建函数或操作系统句柄，不会因为 Go wrapper 被回收就自动释放。

SetFinalizer 的语义是：当 wrapper 不再可达时，运行时把它关联的 finalizer 排入执行队列。这个动作没有确定的业务时间点，也不保证程序退出前一定执行。因此，C 资源的正常路径必须是显式关闭，finalizer 只能降低忘记关闭造成泄漏的概率。

最小可用写法：Close 主路径，finalizer 做兜底

一个稳妥的 wrapper 至少要做到三点：把 C 指针放在受保护的字段里；关闭时先“摘走”指针再调用 C 的释放函数；释放完成后清除 finalizer。下面的 C 函数名只表示常见库接口形状，真实项目需要替换成目标库的声明。

/* 这里的声明只展示 C 资源的创建、使用和释放边界。 */
extern void *resource_open(void);
extern int resource_use(void *p, const void *buf, size_t n);
extern void resource_free(void *p);

type Resource struct {
    mu  sync.Mutex
    ptr unsafe.Pointer
}

func OpenResource() (*Resource, error) {
    // 创建成功后，wrapper 负责保存 C 句柄的所有权。
    ptr := C.resource_open()
    if ptr == nil {
        return nil, errors.New("resource_open failed")
    }

    r := &Resource{ptr: ptr}
    // finalizer 只作为遗漏 Close 时的最后一道防线。
    runtime.SetFinalizer(r, finalizeResource)
    return r, nil
}

func (r *Resource) Close() error {
    r.mu.Lock()
    ptr := r.ptr
    // 先把所有权从 wrapper 摘掉，让重复 Close 和 finalizer 都看见 nil。
    r.ptr = nil
    r.mu.Unlock()

    if ptr == nil {
        // 关闭操作设计成幂等，调用方可以安全地 defer Close。
        return nil
    }

    // C 侧释放可能较慢或返回错误，真实库应在这里保留错误语义。
    C.resource_free(ptr)
    // 确保 wrapper 活到最后一次 cgo 调用返回。
    runtime.KeepAlive(r)
    // 正常路径已经释放资源，不再保留兜底 finalizer。
    runtime.SetFinalizer(r, nil)
    return nil
}

func finalizeResource(r *Resource) {
    r.mu.Lock()
    ptr := r.ptr
    // finalizer 与显式 Close 共用同一个摘指针动作，避免重复释放。
    r.ptr = nil
    r.mu.Unlock()
    if ptr != nil {
        C.resource_free(ptr)
        // 让 finalizer 内的 C 调用也有清楚的存活边界。
        runtime.KeepAlive(r)
    }
}

这里的关键不在于把所有清理逻辑都塞进 finalizer，而在于把“资源是否还归 wrapper 所有”收敛成一个可加锁的状态。显式 Close 和 finalizer 都先将 ptr 置为 nil，随后只有拿到非空指针的一方负责调用 C 的释放函数。

为什么最后一次 cgo 调用后还要 KeepAlive

编译器会根据后续是否仍使用 Go 变量来判断它是否还需要保持可达。若一个方法把 wrapper 中的句柄传给 C，最后一次使用 wrapper 的动作可能被认为已经发生在 cgo 调用入口处；此后若没有新的 Go 层使用，finalizer 可能在 C 调用真正完成前被调度。

正确位置是“最后一次可能依赖 wrapper 的 cgo 调用之后”，而不是函数开头，也不是随意放在 defer 中。它只延迟 finalizer 的触发，不会替 C 代码修复非法指针，也不会延长 C 资源本身的生命周期。

func (r *Resource) Use(buf []byte) error {
    r.mu.Lock()
    ptr := r.ptr
    r.mu.Unlock()
    if ptr == nil {
        return errors.New("resource is closed")
    }

    // 这次 cgo 调用使用了 wrapper 持有的 C 句柄。
    if rc := C.resource_use(ptr, unsafe.Pointer(&buf[0]), C.size_t(len(buf))); rc != 0 {
        // 真实项目应把 C 库错误码映射成稳定的 Go 错误。
        return fmt.Errorf("resource_use failed: %d", int(rc))
    }
    // 这是最后一次使用 r 的位置，防止 finalizer 提前释放句柄。
    runtime.KeepAlive(r)
    return nil
}

如果 buf 可能为空，示例中的 &buf[0] 还需要改成由库约定的空指针传递方式；这属于参数边界，不能因为加入了 KeepAlive 就忽略。

把关闭动作设计成一个小状态机

当 C 资源存在子对象、回调或父子句柄时，不要依靠多个 finalizer 的偶然顺序。更可靠的做法是让一个 Go owner 统一掌握关闭顺序：先停止回调和并发使用，再释放子资源，最后释放父资源；主动关闭后清除 owner 的 finalizer。

如果 C 库要求在创建它的线程上关闭，finalizer 甚至可能不是可接受的兜底方案。此时应把线程亲和性纳入显式 owner 的生命周期，必要时使用 runtime.LockOSThread 管理调用线程，并让 finalizer 只记录遗漏或安排一个安全的释放队列，而不是直接调用受线程限制的 C API。

cgo 指针规则不能用 finalizer 绕过

C 代码可以持有 C 内存，但不能随意把 Go 指针保存到 C 的全局变量或长期对象中。runtime.KeepAlive 只保证 Go 对象在指定位置之前保持可达，不会把 Go 指针变成可由 C 永久持有的句柄。

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

    r.mu.Lock()
    ptr := r.ptr
    r.mu.Unlock()
    if ptr == nil {
        return errors.New("resource is closed")
    }

    // C 函数只能在调用期间读取 data，不能把 Go 指针存起来。
    if rc := C.resource_consume(ptr, unsafe.Pointer(&data[0]), C.size_t(len(data))); rc != 0 {
        return fmt.Errorf("resource_consume failed: %d", int(rc))
    }
    // 调用返回后仍明确保留 wrapper 的存活边界。
    runtime.KeepAlive(r)
    return nil
}

需要长期保存数据时，应改为在 C 侧复制到自己的内存，或使用符合 cgo 规则的句柄设计；不要把“加一个 finalizer”当成指针所有权方案。

五个容易把释放顺序写错的地方

1. 只设置 finalizer，不提供 Close：释放时间不可预测，程序退出时也不能把它当成可靠清理机制。
2. Close 之后没有清空指针：finalizer 仍可能看到旧句柄，导致 double free 或访问已释放内存。
3. KeepAlive 放在 cgo 调用前：它保护不到调用返回后的窗口，应该放在最后一次相关调用之后。
4. 把 C 指针保存进 Go wrapper 后再交给 C 长期持有：这仍可能违反 cgo 指针规则，finalizer 不会改变规则。
5. 用多个 finalizer 拼父子资源顺序：C 指针关系通常不会被 Go 垃圾回收器识别，应由一个显式 owner 统一关闭。

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

正式封装可以为每个 wrapper 记录创建次数、显式关闭次数、finalizer 兜底次数和 C 错误码。不要在 finalizer 中做复杂业务逻辑，也不要为了等待它执行而在生产代码里强制 GC；这些指标的作用是发现调用方遗漏 Close、C API 返回失败或关闭路径存在竞争。

type CloseStats struct {
    Explicit uint64
    Fallback uint64
}

func (r *Resource) Close() error {
    // 统计应与摘指针动作使用同一把锁，避免重复 Close 被计数两次。
    r.mu.Lock()
    if r.ptr == nil {
        r.mu.Unlock()
        return nil
    }
    ptr := r.ptr
    r.ptr = nil
    r.mu.Unlock()

    // 生产代码可在这里记录一次显式关闭，再执行 C 释放。
    C.resource_free(ptr)
    runtime.KeepAlive(r)
    runtime.SetFinalizer(r, nil)
    return nil
}

排查顺序可以固定为：先看 wrapper 是否已进入 Closed，再看 C 释放函数是否返回错误，最后看 finalizer 兜底计数是否异常上升。这样能把“GC 什么时候运行”的不确定性，转化为“哪条关闭路径拿到了资源所有权”的确定问题。

常见问题

finalizer 会在程序退出前一定运行吗？

不能这样假设。它由运行时在对象不可达后排队执行，执行时机不适合作为业务清理协议；需要保证落盘、提交或关闭的动作，都应由显式 API 完成。

Close 里调用 SetFinalizer(r, nil) 就足够避免重复释放吗？

不够。清除关联和 C 释放之间仍可能存在并发窗口，真正的防线是加锁摘走指针，让显式 Close 与 finalizer 只有一个路径拿到非空句柄。

KeepAlive 能保证 C 资源不被释放吗？

它只保证传入的 Go 对象在指定位置之前保持可达，不会替代 C 资源的所有权管理，也不能修复 C 保存 Go 指针、越界访问或线程亲和性错误。

多个 wrapper 有父子关系时怎样排序？

把释放顺序写进一个显式 owner：停止新请求，等待正在进行的调用，释放子资源，最后释放父资源。不要把 C 侧的隐式关系交给多个 finalizer 推断。

参考资料

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