Go runtime.Pinner 怎么让指针在 cgo 调用期间保持地址不变

runtime.Pinner 的用法是：先对要交给 C 的 Go 对象调用 Pin，让对象在固定期内不会被垃圾回收器移动或释放；等 C 不再持有或访问该指针后，再调用 Unpin。不过要先分清一个容易被忽略的边界：如果 Go 指针只是作为 C 函数参数传入，而且 C 不保存它，那么这块内存在该次 cgo 调用期间已经被隐式固定，通常不必额外创建 Pinner。

官方文档：https://pkg.go.dev/runtime#Pinner

cgo 指针规则：https://pkg.go.dev/cmd/cgo#hdr-Passing_pointers

先判断是否真的需要显式固定

Go 1.21 加入了 runtime.Pinner。它不是所有 cgo 指针参数的必选包装，而是用来把“固定期”从一次函数调用扩展到更明确的范围。可以按下表判断：

最小可用写法：Pin 后在 C 不再访问时 Unpin

下面的例子把字节数组的首元素地址传给 C。示例显式使用 Pinner，重点是展示生命周期写法，而不是说明每个同步 C 调用都必须这样做。

package main

/*
#include 

static unsigned char first_byte(void *data, size_t n) {
    // C 只在本次调用内读取数据，不保存 data 指针。
    if (data == NULL || n == 0) {
        return 0;
    }
    return ((unsigned char *)data)[0];
}
*/
import "C"

import (
	"fmt"
	"runtime"
	"unsafe"
)

func main() {
	buf := []byte{7, 8, 9}
	if len(buf) == 0 {
		// 空切片没有可传递的首元素地址。
		return
	}

	var pinner runtime.Pinner
	pinner.Pin(&buf[0])
	defer pinner.Unpin() // C 完全不再访问该地址后再解除固定。

	value := C.first_byte(unsafe.Pointer(&buf[0]), C.size_t(len(buf)))
	runtime.KeepAlive(buf) // 明确要求 buf 至少存活到 C 调用结束。
	fmt.Println(byte(value))
}

Pin 接受任意指针类型或 unsafe.Pointer。零值 runtime.Pinner 可以直接使用；一次 Pinner 可以固定多个对象，而 Unpin 会解除它当前管理的全部固定。官方文档也鼓励在 Unpin 后复用同一个 Pinner，避免重复初始化。

外层固定不等于内部指针自动固定

最常见的误区是只固定结构体本身，却让 C 继续解引用结构体中的 Go 指针。官方规则明确指出：如果已固定对象内部还包含指向其他 Go 对象的指针，而且 C 会访问那些对象，那么对应对象也要分别固定。

type Block struct {
	Data *byte
	Size int
}

func pinBlock(block *Block, data []byte) runtime.Pinner {
	var p runtime.Pinner
	p.Pin(block) // 固定外层结构体，保证结构体地址稳定。
	if len(data) > 0 {
		p.Pin(&data[0]) // C 会解引用 Data 时，底层字节也要单独固定。
		block.Data = &data[0]
		block.Size = len(data)
	}
	return p // 调用方必须持有 Pinner，直到 C 不再访问这些对象。
}

这里还要注意切片边界：把指针传给数组或切片元素时，cgo 规则把相关 Go 内存视为整个数组或整个切片底层数组。不要一边让 C 持有地址，一边在 Go 侧通过 append 换掉底层数组，再假定旧地址仍代表当前切片。

C 要跨调用保存指针时，把 Pinner 放进资源所有者

如果 C 把 Go 指针保存到全局变量、句柄或原生对象中，那么 defer pinner.Unpin() 不能简单放在注册函数末尾，因为注册函数返回后 C 仍在使用该地址。更稳妥的做法是让持有原生资源的 Go 对象同时持有 Pinner，并在显式关闭时按顺序释放：

1. 先通知 C 停止访问并删除保存的 Go 指针；
2. 确认原生侧引用已经清除；
3. 再调用 Unpin；
4. 最后清理 Go 侧资源。

Pinner 变得不可达后，运行时会在之后自动解除其对象，避免永久泄漏，但这不是正常资源释放方案。只要 C 还保留指针，就必须让 Pinner 保持可达；依赖自动清理会把 C 的使用期和 Go 的回收时机割裂。

从旧写法迁移时检查这几个风险

• 只保存 uintptr：uintptr 不是对象生命周期承诺，不能替代 Pinner。
• 过早 Unpin：只要 C 仍保存地址，解除固定就破坏了跨调用保存的前提。
• 重复 Pin 次数不匹配：同一块内存可以被多次固定，但解除固定的次数必须与固定次数匹配。
• 把切片头长期交给 C：应固定并传递明确元素地址；若需要独立所有权，可改用 C.CBytes 复制到 C 堆，并负责释放。
• 把任意 Go 值长期保存到 C：若 C 只需要一个标识而不是原始地址，优先考虑 runtime/cgo.Handle。

回归检查与迁移清单

默认的 GODEBUG=cgocheck=1 会执行成本较低的动态检查。需要更完整的指针规则检查时，应在构建时启用实验选项，而不是把它当作普通运行时开关：

# 构建时启用更完整但更慢的 cgo 指针检查。
GOEXPERIMENT=cgocheck2 go test ./...

迁移完成前，可以用下面的清单逐项核对：

• 项目最低 Go 版本是否已经设为 1.21 或更高；
• C 是否只在当前调用中访问指针，还是会跨调用保存；
• C 能访问到的每个 Go 对象是否都在相应期间保持固定；
• 清除 C 引用是否发生在 Unpin 之前；
• 是否错误地用 unsafe.Pointer、uintptr 或 KeepAlive 代替固定；
• 资源关闭路径和异常路径是否都会执行同一套释放顺序。

常见问题

只在一个同步 cgo 调用里读取 []byte，需要 Pinner 吗？

通常不需要。传给 C 函数的 Go 指针在调用期间会被隐式固定；前提是 C 不在返回后保留它，而且可达内存不包含 C 会访问的未固定 Go 指针。

runtime.KeepAlive 能替代 runtime.Pinner 吗？

不能。KeepAlive 只保证对象在指定程序点之前仍然可达；Pinner 管理的是对象处于固定状态的时间范围，两者解决的问题不同。

Pin 一个结构体后，它指向的所有对象都会固定吗？

不会。若 C 会访问结构体内的 Go 指针所指对象，那些对象必须分别固定。

Pinner 能长期固定 string 或 slice 吗？

不能把包含 Go 指针的 string、slice、map、chan 等值本身直接作为可长期保留的 C 数据。应根据需求传递并固定明确的底层对象、复制到 C 内存，或使用 runtime/cgo.Handle 传递句柄。