Go cgo 为什么不能把 Go 指针长期保存在 C 内存里

在 cgo 里，把 unsafe.Pointer 交给 C 函数本身不一定有问题；危险的是 C 把这个 Go 指针写进全局变量、结构体或异步任务上下文，并在本次 cgo 调用返回后继续使用。默认规则是：C 只能在调用期间借用符合条件的 Go 指针，调用结束后不能保留副本。若确实需要跨调用持有，要改用 runtime/cgo.Handle、C 自有内存，或在严格条件下使用 runtime.Pinner。

Go 官方文档：https://pkg.go.dev/cmd/cgo

问题不在地址，而在 GC 看不见这条引用

Go 运行时负责追踪 Go 堆中的对象和指针关系，C 分配的内存则不属于 Go GC 的常规扫描范围。如果 C 把一个未固定的 Go 指针藏在自己的内存里，Go 运行时无法把这份 C 侧记录当作普通 Go 引用来管理。对象可能被判定为不再需要，未来的运行时实现也可能调整对象位置；即使当前版本的 GC 通常不移动对象，也不能把实现细节当作跨语言 ABI 保证。

因此，规则关注的不是“这个地址现在看起来还有效”，而是运行时能否在整个生命周期内证明它有效。一次 cgo 调用期间，运行时可以围绕传入参数建立受控边界；调用返回后，若 C 仍保留指针，生命周期便越过了这个边界。

最常见的错误：把 Go 对象地址当回调上下文

很多 C 库会接收一个 void* 上下文，并在稍后的回调里原样传回。直接把 Go 结构体地址塞进去很诱人，但异步回调往往发生在原 cgo 调用已经结束之后，这正是“长期保存”的典型场景。把指针转成 uintptr 再存也不会改变它的来源和生命周期；数值转换不是所有权转换。

type State struct {
    Name string
}

func registerWrong(s *State) {
    // 错误思路：C 会在本次调用返回后继续保存并使用这个 Go 指针
    C.remember(unsafe.Pointer(s))
}

这里的 State 还包含 string，而字符串值内部带有指向 Go 内存的数据指针。cgo 的限制不仅检查最外层地址，也关心传递区域是否包含未固定的 Go 指针。类似地，slice、map、channel、func 和 interface 都不是一个可以随意交给 C 长期保存的纯字节块。

方案一：用 cgo.Handle 保存 Go 值身份

如果 C 只需要保存一个上下文标识，并在回调时把它交还给 Go，runtime/cgo.Handle 通常是最稳妥的方案。Handle 的底层是足以容纳指针位模式的整数，但它代表的是运行时维护的句柄，不是把 Go 指针伪装成整数。C 保存整数令牌，真正的 Go 值仍由 Go 侧句柄表管理。

package main

/*
#include 
static uintptr_t saved;
static void remember(uintptr_t h) { saved = h; }
static uintptr_t recall(void) { return saved; }
*/
import "C"

import "runtime/cgo"

type State struct {
    Name string
}

func main() {
    // NewHandle 可以代表包含 Go 指针的任意 Go 值
    h := cgo.NewHandle(&State{Name: "worker"})
    C.remember(C.uintptr_t(h))

    // C 回传整数令牌后，Go 再取回原值
    state := cgo.Handle(C.recall()).Value().(*State)
    _ = state

    // 必须等 C 不再保存和回传该令牌后再释放
    h.Delete()
}

Delete 是显式退出协议的一部分。删除过早，后续回调使用旧句柄会失败；永不删除则会持续占用句柄资源。工程上应把“注销 C 回调”和“删除 Handle”放在同一个关闭流程里，并保证先阻止新回调、等待在途回调结束，再执行 Delete。

方案二：需要长期字节所有权时使用 C 内存

若 C 库要长期读取一段配置、消息或二进制数据，最清晰的所有权模型通常是把数据复制到 C 分配的内存。这样 C 持有的是 C 指针，不会把 Go 堆对象隐藏到 GC 视野之外。代价是一次复制，以及必须明确调用 free。

package main

/*
#include 
static void remember_bytes(void *p, size_t n) { /* 由真实库保存 p 和 n */ }
static void forget_bytes(void) { /* 由真实库停止访问 */ }
*/
import "C"

import "unsafe"

func keepBytesInC(data []byte) func() {
    // C.CBytes 在 C 堆上分配并复制数据
    p := C.CBytes(data)
    C.remember_bytes(p, C.size_t(len(data)))

    return func() {
        // 先让 C 停止访问，再释放 C 内存
        C.forget_bytes()
        C.free(unsafe.Pointer(p))
    }
}

这类方案适合“C 真正拥有并消费数据”的接口。若数据会由 C 修改，Go 要读取结果时应通过明确的拷贝函数取回，不要同时让 Go slice 和 C 指针对同一生命周期做模糊管理。

方案三：确实要稳定地址时使用 runtime.Pinner

从 Go 1.21 起，runtime.Pinner 可以显式固定 Go 对象。C 可以在调用返回后保留指向该对象的指针，但前提是对象在完整持有期内一直处于 pinned 状态。调用 Unpin 之前，必须先确保 C 已删除指针、停止异步工作并且不会再回调使用它。

buf := make([]byte, 4096)
var pinner runtime.Pinner

// 固定的是底层字节对象，而不是包含数据指针的 slice 头
pinner.Pin(&buf[0])
C.remember_buffer(unsafe.Pointer(&buf[0]), C.size_t(len(buf)))

// ... C 可以在此期间继续使用已固定的地址 ...

C.forget_buffer()
pinner.Unpin()

// 保证 Go 侧在此之前仍保持 buf 活跃，但它不替代 Pin
runtime.KeepAlive(buf)

Pinner 不是“让任意 Go 值都能交给 C”的通行证。字符串、slice、map、channel、func、interface 等值本身包含 Go 指针，不能把它们的头部作为长期 C 数据保存。若被固定对象内部还含有 C 需要访问的其他 Go 指针，相应对象也必须分别满足固定要求。实践中，Pinner 更适合无 Go 指针的固定缓冲区或与原生 API 对接的简单对象。

三种安全方案怎么选

如果拿不准，先问两个问题：C 需要的是“对象身份”还是“可直接读写的地址”？数据最终由谁释放？身份优先 Handle，C 所有权优先 C 内存，只有 API 明确要求稳定地址时再考虑 Pinner。

runtime.KeepAlive 为什么不能替代 Pinner

runtime.KeepAlive(x) 的作用是让编译器和 GC 认为 x 至少活到该调用位置。它可以解决 Go 侧最后一次显式使用早于原生调用结束的问题，但不会把 C 内存纳入 Go GC 扫描，也不会授权 C 在函数返回后无限期保存未固定的 Go 指针。KeepAlive 解决“何时仍可达”，Pinner 解决“地址在固定期间能否被 C 保留”，二者不是同一个问题。

用运行时检查尽早暴露违规

cgo 默认启用代价较低的动态指针检查，即 GODEBUG=cgocheck=1。构建时启用 GOEXPERIMENT=cgocheck2 可以获得更完整的检查，但会增加开销。检查能帮助发现“未固定 Go 指针写入非 Go 内存”等问题，却不是绕过规则的许可证；unsafe 可能让某些违规暂时逃过检查，程序仍可能在压力、GC 或版本升级时出现不可预测故障。

常见问题

把 Go 指针先转成 uintptr，C 就能长期保存吗？

不能。转换只改变表示形式，不会改变对象归属、固定状态和生命周期。需要跨 C 保存身份时使用 cgo.Handle。

C 能长期保存 &buf[0] 吗？

只有在底层对象适合固定、已用 runtime.Pinner 固定，并且直到 C 删除引用前都没有 Unpin 时才可以。仅调用 KeepAlive 不够。

为什么复制到 C 内存反而更简单？

因为所有权和释放责任清晰：C 使用 C 指针，Go GC 不需要追踪这段内存。对长期字节数据而言，一次复制通常比跨运行时共享悬空地址更容易维护。