Go cgo.Handle 管理 Go 值跨语言传递

把一个 Go 的结构体、map 或回调函数交给 C 保存，最容易踩到的坑不是类型转换，而是 Go 垃圾回收器和 cgo 指针规则。实用的做法是：Go 侧用 cgo.NewHandle 登记值，把返回的整数传给 C；C 只保存这个整数，回调时再交还给 Go，由 cgo.Handle(token).Value() 取回原值。C 不需要、也不应该把 Go 指针当作长期句柄保存。

cgo.Handle 把 Go 值变成可回传的整数令牌

先把对象关系分开：Go 侧有一个 *bridgeState，句柄表负责把它和整数关联；C 侧只看到 uintptr_t；回调再次进入 Go 后，才通过句柄找回状态。这条链路避免了把包含 map、slice 或函数的 Go 值直接塞进 C 内存。

用 NewHandle 注册状态，再让 C 只保存 token

下面的示例模拟 C 保存一个回调令牌并在稍后触发。示例中的 C 函数只持有整数，真正的业务状态仍由 Go 管理。

package main

/*
#include 

extern void go_on_event(uintptr_t token, int code);

// 说明：真实 C 库可以把 token 存到自己的上下文结构中。
static inline void emit_event(uintptr_t token, int code) {
    go_on_event(token, code);
}
*/
import "C"

import (
    "fmt"
    "runtime/cgo"
)

type bridgeState struct {
    name string
}

//export go_on_event
func go_on_event(token C.uintptr_t, code C.int) {
    // 说明：C 侧若误用零值或已删除的 token，避免把异常继续扩散。
    defer func() {
        if recover() != nil {
            fmt.Println("stale cgo handle")
        }
    }()
    // 说明：先恢复句柄对应的 Go 值，再做明确类型断言。
    value := cgo.Handle(token).Value()
    state, ok := value.(*bridgeState)
    if !ok || state == nil {
        // 说明：非法句柄不能继续当作业务对象使用。
        fmt.Println("invalid cgo handle")
        return
    }
    fmt.Printf("%s received %d\\n", state.name, int(code))
}

func main() {
    state := &bridgeState{name: "worker-1"}
    handle := cgo.NewHandle(state)

    // 说明：C 侧得到的是整数 token，不是 state 的 Go 指针。
    C.emit_event(C.uintptr_t(handle), C.int(200))

    // 说明：只有在 C 不会再次回调后才能删除句柄。
    handle.Delete()
}

NewHandle 会让句柄指向的 Go 值保持可取回，但不会替你管理 C 的生命周期。如果 C 会异步回调，就不能把 Delete 机械地写在发起调用的函数末尾，而要放到 C 侧确认注销、任务结束或上下文销毁之后。

Value 之后的类型、并发与错误处理要单独设计

Value() 返回 any，建议让一个句柄只对应一种约定类型。回调入口先断言，再调用对象方法；不要把任意句柄直接强转成业务结构体。多个 C 线程可能同时回调时，句柄取值本身不等于业务状态线程安全，状态里的计数器、缓存或 channel 仍需要互斥、原子操作或专门的事件队列。

Delete 时机决定跨语言状态能否安全回收

句柄的生命周期可以压缩成四个检查点：注册、传递、回调、注销。C 若只在同步调用期间使用 token，调用返回后即可删除；C 若把 token 存入连接或事件循环，必须提供显式的 stop/unregister 路径。删除之后再次调用 Value() 属于失效句柄使用，不能靠捕获 panic 当成正常流程。

还要区分两件事：句柄规避的是“长期把含 Go 指针的值交给 C”的问题；它不代表 C 可以随意写入 Go 内存，也不替代 C.malloc 对应的 C.free。需要传输大块字节时，通常应明确选择复制、C 分配的缓冲区，或按照当前 cgo 指针规则使用可固定的内存，而不是把句柄当成万能指针。

相关问题

cgo.Handle 能否直接转成 Go 指针？

不能。它的用途是把 Go 值映射成可跨语言传递的整数，再由 Go 侧取回，不是内存地址转换工具。

句柄应该什么时候 Delete？

在 C 已停止保存和回调该 token 之后删除；同步调用可在调用返回后删除，异步场景需要显式注销或关闭流程。

多个回调线程能共享一个句柄吗？

可以共享同一个有效 token，但被取回的 Go 对象必须自行处理并发；句柄表不会替业务字段提供锁。

什么时候不需要 Handle？

只在一次 cgo 调用中传递不含长期 Go 指针的数据，或使用明确的 C 内存和复制边界时，通常不必为此额外建立句柄。