Go cgo 怎样明确释放 C 分配的内存

在 Go 服务里接入 C 库时，最容易被忽略的是：Go 的垃圾回收器只认识 Go 管理的对象，不会替你回收 C 堆上的 malloc 内存。只要代码调用了 C.CString、C.CBytes，或者接收了 C 函数返回的缓冲区，就要先写清“谁分配、谁释放、何时释放”。

官方资料：https://pkg.go.dev/cmd/cgo

最稳妥的规则是：C 分配的内存由 C 侧约定的释放函数回收，Go 只负责在明确的生命周期节点调用它；Go 的指针不能在未满足规则时被 C 长期保存。

先分清两块堆和一条所有权规则

可以把一次 cgo 调用拆成三个对象：Go 侧的字符串或切片、C 侧的连续缓冲区、以及调用它们的生命周期。C.CString 会在 C 堆上分配一份以零字节结尾的字符串，C.CBytes 会在 C 堆上复制一份字节数组；它们都不会因为 Go 变量离开作用域而自动释放。

生产代码里建议把“获得指针”与“登记释放”放在相邻位置。这样审查者能在同一段代码里看到资源责任，而不是依赖调用方记忆。

给 C.CString 和 C.CBytes 配对释放

下面这个包装函数只保留一个清晰的责任范围：把 Go 字符串复制到 C 堆，调用 C 函数，再在函数返回前释放。即使 C 函数返回错误，defer 也会执行，避免错误路径留下泄漏。

package bridge

// #include 
//
// // C 侧只在调用期间读取文本，不把指针保存到函数外。
// static int consume_text(const char *text) {
//     return text != NULL && text[0] != '\0' ? 0 : -1;
// }
import "C"

import (
    "fmt"
    "unsafe"
)

func SendText(text string) error {
    // C.CString 在 C 堆分配，调用方必须负责释放。
    cText := C.CString(text)
    defer C.free(unsafe.Pointer(cText))

    // C 函数只在本次调用内读取 cText，返回后不再持有它。
    if rc := C.consume_text(cText); rc != 0 {
        return fmt.Errorf("C.consume_text failed: code=%d", int(rc))
    }
    return nil
}

字节切片的处理方式相同，只是 C.CBytes 产生的是一段 C 缓冲区。长度要同时传给 C，不能把它当成自动以零字节结尾的字符串。

func SendBytes(data []byte) error {
    // C.CBytes 复制 data 到 C 堆；空切片不应被当作有效输入。
    if len(data) == 0 {
        return fmt.Errorf("empty payload")
    }
    cData := C.CBytes(data)
    defer C.free(cData)

    // 长度显式传递，C 侧不依赖末尾的 NUL 判断边界。
    if rc := C.consume_bytes(cData, C.size_t(len(data))); rc != 0 {
        return fmt.Errorf("C.consume_bytes failed: code=%d", int(rc))
    }
    return nil
}

区分“已经复制”与“仍然拥有指针”

接收结果时不要只看类型像不像字符串。C.GoString 会把 C 字符串复制成 Go 字符串，复制完成后，Go 字符串由 GC 管理；但 C 原始指针是否需要释放，仍取决于它是由谁分配以及 API 如何规定。

// #include 
//
// // 调用方拥有返回值，必须用 release_buffer 释放同一块 C 内存。
// static char *make_message(void) {
//     char *p = (char *)malloc(32);
//     if (p == NULL) return NULL;
//     snprintf(p, 32, "cgo message");
//     return p;
// }
// static void release_buffer(char *p) { free(p); }
import "C"

func ReadMessage() (string, error) {
    // 这里拿到的是 C 指针，不能只转成 Go 字符串就丢掉原指针。
    ptr := C.make_message()
    if ptr == nil {
        return "", fmt.Errorf("C.make_message returned nil")
    }
    defer C.release_buffer(ptr)

    // GoString 负责复制；defer 负责释放原始 C 缓冲区。
    return C.GoString(ptr), nil
}

如果第三方库规定必须调用 library_free，就不要用 C.free 替代。不同运行库、不同编译器或不同模块边界下，分配器并不一定相同；释放函数必须与分配契约配对。

跨边界长期持有时，先处理 Go 指针规则

释放 C 内存只是第一层责任，另一层是不要把 Go 指针交给 C 后任由 C 保存。cgo 文档要求：传给 C 的 Go 指针必须指向满足规则的内存，C 不能在调用返回后继续保存普通 Go 指针；字符串、切片等带 Go 指针语义的值不能被 C 长期保留。

如果 C 库必须异步保存数据，常见选择有两种：第一，把数据复制到 C 堆并由 C API 管理；第二，不传裸 Go 指针，改用 runtime/cgo.Handle 保存 Go 值的句柄，并在 C 不再使用时显式删除句柄。句柄本身也需要生命周期设计，不能因为用了类型安全的名字就省略释放。

import "runtime/cgo"

func NewHandle(value any) cgo.Handle {
    // 句柄把 Go 值映射成整数标识，C 侧保存标识而不是 Go 裸指针。
    return cgo.NewHandle(value)
}

func CloseHandle(h cgo.Handle) {
    // C 已经确认不再回调后才能删除，否则后续访问会失效。
    h.Delete()
}

上线前用五项清单检查释放责任

1. 每个 C.CString、C.CBytes 或 C 分配函数是否都有明确的释放点。
2. 释放函数是否与分配函数属于同一套 API，避免跨 allocator 释放。
3. 错误返回、超时和提前退出路径是否仍然执行清理。
4. Go 字符串或切片是否被 C 保存到了调用返回之后。
5. 封装函数的文档是否写明“调用期间使用”或“调用方拥有并负责释放”。

可以把这套规则压缩成一句话：C.CString 和 C.CBytes 产生的 C 内存要显式释放，C.GoString 只是复制结果，C API 返回的原始指针要按它自己的释放契约处理，而 Go 指针不能被 C 无期限保存。

常见问题

调用 C.GoString 后还要 free 吗？

Go 字符串结果本身不需要手动释放，但传给 C.GoString 的原始 C 指针是否需要释放，仍要看分配来源和 API 契约。复制不等于释放。

可以直接用 Go 的 finalizer 回收 C 内存吗？

不建议把 finalizer 当作确定性释放机制。C 资源需要在明确的关闭点释放，finalizer 最多作为遗漏的兜底提示，不能代替 defer、Close 方法或 API 约定。