Go cgo 指针在调用后过早回收怎么办

Go 的 cgo 指针问题，最容易混淆的是“对象还可达”和“这块内存可以被 C 长期持有”并不是一回事。runtime.KeepAlive(x) 只把 x 标记为在调用点仍然可达，保证对象不会在该点之前被回收或触发 finalizer；它不会把普通 Go 指针变成可以跨 cgo 调用保存的 C 指针。

因此，先看 C 函数的使用边界：如果 C 只在本次调用期间读取指针，重点是遵守 cgo 指针规则，并在带 finalizer 的资源对象最后一次使用之后补上 runtime.KeepAlive；如果 C 要把地址保存到异步任务、全局变量或回调上下文里，不能只加 KeepAlive，应改用固定内存、runtime/cgo.Handle 或 C 自己分配的内存。

一句话判断：KeepAlive 解决“最后一次使用前不要过早失活”，Pinner 解决“在明确范围内固定允许的 Go 内存”，Handle 解决“把包含 Go 指针的 Go 值用整数句柄交给 C”。三者不是同一个问题的三个写法。

先把三种生命周期分开

一次 cgo 交互通常同时涉及三个生命周期：Go 变量的可达性、传给 C 的内存是否被固定，以及 C 是否把地址保存到调用之外。排查“调用后过早回收”时，可以先按下面的关系判断：

同步 cgo 调用：把 KeepAlive 放在最后一次使用之后

runtime.KeepAlive 的典型用途是保护一个带 finalizer 的资源所有者。假设 Go 对象里保存着 C 资源句柄，finalizer 会在对象不可达后释放它，那么编译器可能认为对象在最后一次直接引用之后就不再需要。把 KeepAlive 放到 C 调用之后，就能明确告诉运行时：至少到这里仍然需要这个对象。

package main

// #include 
// void native_read(uintptr_t handle);
import "C"

import (
	"runtime"
	"runtime/cgo"
)

type NativeReader struct {
	handle cgo.Handle
}

func (r *NativeReader) ReadOnce() {
	// C 只在本次调用中使用句柄，不把 Go 指针保存到调用之外。
	C.native_read(C.uintptr_t(r.handle))
	// 这里明确保留资源所有者，避免它在最后一次直接使用后过早失活。
	runtime.KeepAlive(r)
}

func (r *NativeReader) Close() {
	// 资源关闭后不再允许 C 继续使用这个句柄。
	r.handle.Delete()
}

这里的重点不是“调用 KeepAlive 就能让 C 永久拿着地址”，而是把资源对象的最后使用点写清楚。若 C 函数只在调用期间消费参数，cgo 会按调用边界处理传入的 Go 指针；但参数指向的内存仍必须满足 cgo 的指针规则，KeepAlive 不能替代这些规则。

代码中的 cgo.Handle 只是让 C 携带一个整数值，并不把 Go 对象地址直接交给 C。句柄对应的 Go 值仍由 Go 侧管理，确认 C 不再回调后要调用 Delete，否则会留下句柄表项。

为什么只加 KeepAlive 仍然可能出错

KeepAlive 的作用点是“调用到这里之前保持可达”。它没有改变以下三件事：

• 它不会解除 cgo 对 Go 指针内容的限制。传给 C 的 Go 内存不能包含未固定的 Go 指针。
• 它不会允许 C 在函数返回后保存普通 Go 指针。调用结束后，隐式固定的时间也结束。
• 它不会替 C 管理异步任务的释放协议。异步回调仍需要明确谁持有状态、何时释放、是否允许并发访问。

例如，下面的写法把 Go 切片的首地址交给 C，并假设 C 把它保存下来。这不是 KeepAlive 能修好的问题：

// #include 
// void remember_buffer(void *p, size_t n);
import "C"

import (
	"runtime"
	"unsafe"
)

func wrongAsync(buf []byte) {
	// 这段只演示风险：C 若保存 p，调用返回后就越过了同步边界。
	C.remember_buffer(unsafe.Pointer(&buf[0]), C.size_t(len(buf)))
	// KeepAlive 只延长到这里，不能让 C 获得跨调用持有资格。
	runtime.KeepAlive(buf)
}

另外，空切片没有可取的首元素，生产代码还要先处理长度为零的情况。更重要的是，异步 C 代码若真的要长期持有数据，通常应让 C 用 C.malloc 分配缓冲区，由明确的释放函数回收；Go 侧只传递长度、状态码或句柄，而不是把 Go 切片地址当作长期所有权。

需要固定内存时，再考虑 runtime.Pinner

如果业务确实需要 C 在调用返回后继续持有某段 Go 内存，runtime.Pinner 才是讨论对象，但它有严格前提：内存必须是允许固定的 Go 内存，内存中不能有未固定的 Go 指针，而且 C 只能在这段内存保持 pinned 期间保存该指针。固定不是“让任何 Go 对象都能安全交给 C”。

// #include 
// void start_async(void *p, size_t n);
// void stop_async(void *p);
import "C"

import (
	"runtime"
	"unsafe"
)

type PinnedBuffer struct {
	data  []byte
	pinner runtime.Pinner
}

func (b *PinnedBuffer) Start() {
	if len(b.data) == 0 {
		return
	}
	// byte 数组不含 Go 指针，适合在满足接口约定时固定并传给 C。
	b.pinner.Pin(&b.data[0])
	C.start_async(unsafe.Pointer(&b.data[0]), C.size_t(len(b.data)))
}

func (b *PinnedBuffer) Stop() {
	if len(b.data) == 0 {
		return
	}
	// 先通知 C 不再使用，再解除固定；顺序由双方协议共同保证。
	C.stop_async(unsafe.Pointer(&b.data[0]))
	b.pinner.Unpin()
}

上例的关键不在 API 调用顺序本身，而在协议：stop_async 必须确认 C 已经停止读写，之后 Go 才能 Unpin。如果 C 需要保存的是一个包含字符串、切片、map、interface 或其他 Go 指针的复杂对象，直接 Pinner 通常不是合适路线；应传递 C 可理解的扁平数据，或者使用 Handle。

需要把 Go 值交给 C 时使用 cgo.Handle

runtime/cgo.Handle 用一个整数代表 Go 值，适合 C 保存并在之后回调 Go 的场景。C 保存的是句柄值，不是 Go 对象地址；Go 回调时再把句柄还原为值。句柄必须有清晰的创建、使用和删除边界。

// #include 
// void register_callback(uintptr_t handle);
import "C"

import (
	"runtime/cgo"
)

type CallbackState struct {
	Name string
}

func register(state *CallbackState) cgo.Handle {
	h := cgo.NewHandle(state)
	// C 只保存整数句柄，不保存 state 的 Go 指针。
	C.register_callback(C.uintptr_t(h))
	return h
}

//export onCallback
func onCallback(raw C.uintptr_t) {
	h := cgo.Handle(raw)
	state := h.Value().(*CallbackState)
	// 回调完成后再删除，不能提前让 C 继续使用的句柄失效。
	defer h.Delete()
	println(state.Name)
}

真实项目中要根据 C 库的回调注销接口安排 Delete，不能把删除动作无条件放在第一次回调里，除非协议明确只回调一次。并发回调还需要自行保护 CallbackState 的可变字段；Handle 只解决跨语言传值，不自动解决并发同步。

一套可复用的排查顺序

1. 先找保存动作。 搜索 C 侧是否把传入地址写入全局变量、异步任务或回调上下文；只要保存越过本次调用，就不能用 KeepAlive 掩盖问题。
2. 再看参数内容。 确认传入区域是否包含 Go 指针。字符串、切片、map、channel、函数和 interface 等值不能简单当成一段可长期交给 C 的字节。
3. 确认谁拥有释放权。 C 内存由 C 释放，Handle 由 Go 在 C 注销后删除，Pinner 由 Go 在 C 停止使用后解除。
4. 最后补 KeepAlive。 只有在资源对象带 finalizer，且最后一次实际使用发生在某个系统调用或 cgo 调用之前时，才在最后一次使用之后放置 KeepAlive。

可以把最终决策压缩成这张速查表：

常见追问

KeepAlive 应该放在 cgo 调用前还是后？

通常放在最后一次需要该对象的调用之后。它表示“对象至少要活到这里”，所以放在调用前不能覆盖调用期间的生命周期，也不能替代 C 端的异步持有协议。

加了 KeepAlive 还需要遵守 cgo 指针规则吗？

需要。KeepAlive 只影响可达性判断，不能改变哪些 Go 内存允许传给 C、C 能保存多久以及哪些对象必须固定。

cgo.Handle 和 runtime.Pinner 怎么选？

如果 C 需要的是一个 Go 值，优先用 Handle；如果 C 必须直接访问一段满足规则的内存，并且能明确开始和结束时间，再考虑 Pinner。两者都要配合清晰的释放协议。

本文依据 Go 官方 runtime.KeepAlive、cgo 指针传递规则 和 runtime/cgo.Handle 文档整理。遇到具体库时，还要以该库的回调、线程和释放约定为准。