Go cgo.Handle 怎样让 C 安全回调 Go 值

Go 的 cgo.Handle 可以把 Go 值登记成整数标识，让 C 保存或回传这个标识，再由 Go 回调通过 Value 找回原来的值。它解决的是跨语言关联问题，不是让 C 直接读写 Go 对象，更不会自动处理异步回调结束和并发访问。

如果我要给一个 C 插件绑定会话状态，我会先问：插件只需要“记住这是谁”，还是需要读取对象字段？下面用一个假设的同步插件说明我的选择，不把示例当作实际生产运行记录。

官方 API 文档：https://pkg.go.dev/runtime/cgo；cgo 接入说明：https://pkg.go.dev/cmd/cgo。

C 回调只需要关联状态，不需要 Go 对象地址

设想 Go 端有一个 session，其中保存会话标签和回调次数。C 的 invoke 只负责调用 Go 的 GoReport，不读取 session 的字段。对这个负载，我更愿意让 C 接收 uintptr_t 类型的 token：它代表一个登记项，不代表内存地址。

Go 端的 h 是 Handle，登记项关联 state；C 端只能回传 token。真正读取标签、修改计数的是 GoReport。这种划分让 C 的接口不必理解 Go 的字符串、指针或结构体布局。不要把它推广为所有 C 接口都能直接套用：要求 void* 的 API 需要另外设计桥接协议。

我会怎样选择整数句柄而不是强转指针

直接传 Go 指针受到 cgo 指针传递规则约束，值中还可能包含其他 Go 指针。Handle 则把跨语言参数限定为整数，并把对象访问留在 Go 里。我看重的是边界清楚，而不是声称它更快。这里没有性能测量，也不比较两种方案的吞吐量。

下图中的连线只是值、登记项和回调的静态关系，不表示执行先后；重点看 C 边界里没有 session 对象。

NewHandle、Value、Delete 分别承担什么责任

NewHandle(state) 创建关联并占用资源；在明确 Delete 之前，程序必须考虑这份登记仍然存在。它不会因为创建函数返回就自动释放。若登记的是指针，Value 找回的是同一个指针所指的状态，并不是自动复制一份对象供回调独享。

h.Value() 返回关联的 Go 值，类型为接口。下面的 .(*session) 来自“只登记 *session”的应用约定，不是 Handle 自动检查的类型协议。混用不同对象类型时，应设计明确的注册与回调类型规则；错误断言会 panic。

h.Delete() 使句柄失效。零值不是有效句柄，失效句柄调用 Value 或 Delete 会 panic；Delete 不能当成可反复调用的幂等清理。复制 h 或 token 也不会得到新的独立登记项，不能让每个整数副本都负责删除。

同步回调可以把释放责任留给调用方

将下面两个文件放在同一目录。示例要求支持 cgo 的 Go 环境和可用 C 编译器。main.go 的 C 前导注释只写声明，把 invoke 的定义放在 bridge.c：含 //export 的 Go 文件，其前导部分不能混入会造成重复符号的函数定义。

main.go

package main

/*
#include 
// 这里只声明函数，定义放在独立 C 文件。
void invoke(uintptr_t token);
*/
import "C"

import (
    "fmt"
    "runtime/cgo"
)

type session struct {
    label string
    calls int
}

// GoReport 依据应用约定取回会话，只由此回调修改计数。
//export GoReport
func GoReport(token C.uintptr_t) {
    h := cgo.Handle(token)
    state := h.Value().(*session)
    state.calls++
    fmt.Println(state.label, state.calls)
}

func main() {
    state := &session{label: "sample"}
    h := cgo.NewHandle(state)
    // invoke 同步完成回调，且 C 不保留 token，才可在此释放。
    defer h.Delete()
    C.invoke(C.uintptr_t(h))
    // 状态仍由 Go 访问；Handle 不负责释放业务资源。
    fmt.Println("Go sees calls:", state.calls)
}

bridge.c

#include 
#include "_cgo_export.h"

// 同步调用 Go 回调，不保存 token，也不派生后台任务。
void invoke(uintptr_t token) {
    GoReport(token);
}

_cgo_export.h 是 cgo 构建时生成的头文件，不需要手工创建。导出指令必须紧邻对应函数，且 Go 文件保留 import "C"。

# 在新示例目录中初始化模块，只需执行一次。
go mod init example.com/handle-demo
# 连同 bridge.c 一起构建运行，需要 C 编译器。
CGO_ENABLED=1 go run .

读者运行时，应观察到 GoReport 使用 sample 标签，且 main 随后读取的 calls 已增加。这是代码预期，不是本文宣称已执行的测试结果。如果只运行 go run main.go，独立 C 文件可能没有作为完整包参与构建，应使用目录形式的 go run .。编译器缺失、cgo 被禁用与句柄类型错误是不同问题。

换成异步插件后，defer 的位置就不能照搬

我会把上面的 defer 视为同步协议的一部分：invoke 返回前，GoReport 已经结束，C 不再持有 token。若真实插件只是完成注册就返回，却稍后在后台回调，此时在注册函数退出时 Delete，会让后续回调遇到失效句柄。

异步接入需要明确停止新回调的操作、等待正在执行的回调结束的机制，以及 C 不再持有 token 的保证，之后才由唯一清理责任方 Delete。不能仅凭 C 注册函数返回、Go 侧取消信号或一次回调完成，就判断所有使用已经结束。本文不实现异步插件协议，也不声称 Handle 可以替代它。

Handle 的关联管理不等于 session 字段并发安全；若多个回调并发修改 calls，业务状态仍需互斥或其他同步策略。不要让 Delete 与尚未取值的回调竞争。回调边界也不能依靠故意触发 panic 作为正常错误处理。

接入前，我会把这几项写进接口约定

• C 参数为能完整承载 Handle 的 uintptr_t，不截断为固定较小整数，不把整数当指针解引用。
• 注册值的类型与回调中的取值类型一致，零 token 作为无有效关联的标识而不是调用 Value 的输入。
• 只有一个组件负责 Delete；C 不再持有标识、回调不再使用关联时才释放。
• 同步与异步协议分开处理；Go 状态的并发同步和业务资源清理另外安排。

忘记 Delete 会怎样？登记资源仍然保留，不能把垃圾回收当成自动注销协议。Delete 后 state 就不能用了？Delete 删除句柄关联，不等于把 Go 变量手工销毁；如果 Go 还有对 state 的引用，仍按 Go 的对象与并发规则访问。能否在回调里 Delete？只在明确没有任何后续使用、C 已无标识副本且由该回调独占清理职责时考虑；多次回调不能照搬一次性用法。

对我来说，Handle 的价值是让 C 保留身份、让 Go 保留对象访问权。只有把三种 API 与真实回调寿命对应起来，整数句柄才是清晰的桥接设计，而不是藏起来的悬空关联。