Go cgo.Handle 如何安全保存 Go 值：跨语言句柄生命周期与 Delete 时机

Go 代码需要把一个 Go 值交给 C 库保存，并在稍后回调回来时，应该使用 runtime/cgo.Handle，而不是把 Go 指针当成长期有效的 C 指针。句柄负责把 Go 值映射成一个可传递的整数值；回调期间用 Value() 取回它，最后在 C 侧不再使用时调用 Delete()。

cgo.Handle 解决的是“跨边界保存引用”的问题，不会替你决定释放时机。创建一次、取值一次或多次、释放恰好一次，是最重要的约束。

Go 值如何跨过 cgo 边界

cgo 对指针跨边界有严格限制：C 代码不能把带有 Go 指针的 Go 内存长期保存，Go 指针也不能被 C 代码任意留存到调用返回之后。一个回调库往往会把用户数据放进 void*，再在稍后触发回调，这正好越过了短暂调用的安全边界。

cgo.Handle 把 Go 值放在 Go 运行时可管理的位置，再生成一个不透明句柄。C 侧只保存这个句柄的数值；它不需要理解 Go 对象，也不应该把它转换回 Go 指针。

最小用法：让句柄承担回调参数

下面的例子把一个回调需要的 Go 对象放进句柄。示例中的 callbackArg 只在 Go 侧使用，传给 C 的 userData 是句柄对应的整数值。

package bridge

/*
typedef unsigned long long callback_arg;
void register_callback(callback_arg userData);
*/
import "C"

import (
    "fmt"
    "runtime/cgo"
)

type callbackArg struct {
    Name string
}

func Register(name string) cgo.Handle {
    h := cgo.NewHandle(callbackArg{Name: name})
    C.register_callback(C.callback_arg(h))
    return h
}

//export onCallback
func onCallback(userData C.callback_arg) {
    h := cgo.Handle(userData)
    arg, ok := h.Value().(callbackArg)
    if !ok {
        return
    }
    fmt.Println(arg.Name)
}

这里的关键点有两个。第一，cgo.Handle 只是整数句柄，不能把它误当作业务对象；第二，Value() 返回的是 any，类型断言失败时要有明确的兜底动作，不能直接写成一条没有保护的强制断言。

回调完成后什么时候 Delete

如果 C 注册接口会在未来触发回调，Register 返回句柄并不等于调用方可以随时删除它。C 仍可能持有这个数值时，Go 侧提前 Delete()，回调再调用 Value() 就会落到失效句柄上。

更稳妥的做法是把释放责任放到“注销成功”或“一次性回调完成”的路径上。注册失败也要清理刚创建的句柄，避免失败分支把引用永久留在运行时里。

func RegisterOnce(name string) (cgo.Handle, error) {
    h := cgo.NewHandle(callbackArg{Name: name})
    if err := registerInC(h); err != nil {
        h.Delete()
        return 0, err
    }
    return h, nil
}

func Close(h cgo.Handle) {
    unregisterInC(h)
    h.Delete()
}

Close 里的顺序不是装饰：先让 C 停止使用句柄，再删除 Go 侧记录。若注销本身可能和回调并发，仍需由 C 库提供的注销完成语义来保证回调不会继续进入；单独加一个 Go 锁，不能修复 C 库内部未定义的并发协议。

三个容易混淆的边界

把句柄当成可序列化业务 ID

句柄适合在同一个进程、同一套 cgo 桥接协议中传递。它不是数据库主键，也不是可以跨进程重建 Go 对象的稳定 ID。进程重启、模块协议变化或句柄已删除后，原数值都没有业务意义。

重复调用 Delete

Delete() 应当由一个清晰的拥有者调用一次。可以在拥有者结构体中保存关闭状态，配合互斥保护重复关闭；不要让回调、超时任务和用户手动关闭各自“顺手”删除同一个句柄。

回调里忽略类型不匹配

句柄本身不携带业务类型。若不同回调共用一个入口，建议在 Go 值中放一个明确的类型标记，或为不同对象使用独立的回调入口。类型断言失败时记录可诊断信息并停止使用，而不是继续访问未知对象。

排查回调崩溃时先看哪几处

先确认 C 保存的是句柄值而非 Go 指针，再核对回调发生时句柄是否已经被 Delete()。如果问题只在关闭或超时后出现，优先检查注销完成与回调停止之间的竞态，而不是先怀疑垃圾回收器。

最后核对错误路径：C 注册失败、Go 对象初始化失败、回调类型断言失败，都应该有一致的清理策略。只要句柄的创建者和释放者说不清楚，代码就很容易在正常路径看似工作、异常路径却泄漏或崩溃。

相关问题

cgo.Handle 能替代 unsafe.Pointer 吗？

在需要让 C 长期保存 Go 值的场景，优先使用句柄。unsafe.Pointer 不会自动提供生命周期管理，也不能绕过 cgo 的指针规则。

回调结束后一定马上 Delete 吗？

只有确认 C 不会再次使用这个句柄时才可以删除。一次性回调可以在回调协议明确结束后释放；异步注册则通常要等注销完成。

句柄可以在多个 goroutine 中读取吗？

句柄值本身可以被传递，但它对应的 Go 对象是否支持并发访问，要由对象自身的同步方式决定；句柄不会替对象加锁。

小结

把 cgo.Handle 看成“运行时托管的跨语言引用”就不容易走偏：C 侧只保存不透明数值，Go 回调在有效期内取回值，注销完成后由唯一责任方调用 Delete()。真正需要设计的是句柄的拥有权和关闭协议，而不是把句柄包装得更像一个普通指针。