Go runtime/cgo.Handle 如何把 Go 值安全交给 C：句柄表、释放顺序与回调边界

做 Go 和 C 的回调桥接时，最容易卡住的不是函数声明，而是“回调回来时，C 手里到底拿着什么”。如果要把一个包含 Go 指针的 Go 值交给 C，推荐用 runtime/cgo.Handle：Go 侧把值登记成一个整数句柄，C 侧只保存并传回这个整数，最终由 Go 调用 Value() 取回原值。

cgo.Handle 解决的是 Go 值跨 Go/C 边界的标识问题，不是 C 侧的 Go 指针；句柄何时创建、何时回收，以及 C 是否还会回调，必须由调用方明确管理。

为什么回调参数不该直接塞 Go 指针

假设 Go 负责注册一个回调，C 库稍后把上下文参数原样传回。直接把一个 Go 指针放进 C 内存，会撞上 cgo 的指针传递规则：C 代码不能长期保存它收到的 Go 指针副本，除非显式使用 runtime.Pinner，而且这会引入额外的生命周期管理。

Handle 的思路相反。NewHandle 返回的是底层类型为 uintptr 的整数，C 只需要把这个整数当作不透明上下文保存。它不是 Go 指针，Go 再用这个编号从运行时的句柄表中找回原始值。

最小回调链：NewHandle、C.myprint 和 Value

下面的例子把字符串交给 C，再由 C 调回导出的 Go 函数。为了让边界清楚，C 只转发 uintptr_t，不缓存 Go 对象，也不改写句柄。

package main

/*
#include 
extern void MyGoPrint(uintptr_t handle);
static void myprint(uintptr_t handle) {
    MyGoPrint(handle);
}
*/
import "C"

import "runtime/cgo"

//export MyGoPrint
func MyGoPrint(handle C.uintptr_t) {
    h := cgo.Handle(handle)
    value := h.Value().(string)
    println(value)
    h.Delete()
}

func main() {
    h := cgo.NewHandle("hello from Go")
    C.myprint(C.uintptr_t(h))
}

这里的调用链只有四个关键节点：cgo.NewHandle 创建编号，C.myprint 把编号传回 Go，h.Value() 取回字符串，h.Delete() 释放句柄。图片中的节点也只对应这条真实链路，避免把 C 内部并不存在的“句柄对象”画成指针。

支持范围与兼容处理：整数句柄和 void* 上下文不是一回事

如果 C 接口本来就接收 uintptr_t，直接传 C.uintptr_t(h) 最清楚。句柄的零值无效，可以在 C API 中作为哨兵值，但业务代码仍应把“未设置”与“已删除”分开记录。

有些旧 C 接口只接受 void*。这时不能把 Handle 整数硬转为 unsafe.Pointer。官方示例的做法是把 Go 栈上的句柄变量地址传给 C，并保证 C 函数不保存这个指针副本；如果 C 要异步保存上下文，就应改造接口传整数，或重新设计一套明确的 pin 生命周期。

这篇示例依赖 cgo 和可用的 C 编译器。没有 cgo 的构建环境不是把句柄改成普通指针就能兼容的；应在构建标签或适配层中提供不使用 cgo 的实现。

释放顺序决定回调是否会撞上 panic

NewHandle 创建的句柄会占用运行时资源，不能把 Delete 当作可选的“优化”。正确顺序是：先确认 C 已经不再持有句柄值，再删除句柄。若 C 仍可能回调，提前删除后，回调里的 h.Value() 会因为句柄失效而 panic；重复调用 Delete() 也同样不安全。

更稳的做法是让注册对象拥有句柄，并把注销动作设计成幂等的业务状态转换：注销先阻止新的 C 回调进入，让句柄保持 valid 的回调先退出，再执行一次 h.Delete()。这里的等待和互斥属于应用层协议，Handle 本身不会替你协调异步 C 线程。

几个看似能用、实际容易出错的写法

把 Handle 当作 unsafe.Pointer

不行。Handle 是整数句柄，不是指向 Go 值的地址。强转会绕过 cgo 规则，得到一个无法由 C 正确解引用的地址。

回调开头直接 Value，没检查注销状态

如果回调和注销并发，必须先在应用协议中保证回调仍然拥有有效句柄。不要用 recover 把失效句柄的 panic 当作正常竞态；那只会掩盖释放顺序错误。

把句柄泄漏当成“反正只是一个整数”

整数本身很小，但句柄表记录的原始 Go 值可能很大。长连接、插件回调和批量注册场景都应在取消、关闭或注销路径上留下唯一的 h.Delete()。

相关问题

Handle 能否替代所有 C 回调上下文？

不能。它适合把 Go 值作为不透明上下文标识传递；C 仍需遵守线程、回调时机和 ABI 约定，Handle 不会自动让任意 C 线程调用 Go 变安全。

为什么不用全局 map 保存 Go 值？

全局 map 也能实现编号到值的映射，但要自己处理并发访问、编号分配、删除和泄漏。runtime/cgo.Handle 已经提供了这层运行时句柄管理，边界更集中。

最后核对一遍

只要记住一条判断线：C 保存的是整数句柄，Go 才拥有原值和释放权。创建后把句柄安全传回，回调期间先确认它仍有效，C 完全不再使用后再执行一次 Delete。涉及 void*、异步保存或跨线程回调时，优先先改清楚生命周期协议，再谈代码简化。