Go cgo 回调为什么需要先导出 Go 函数

在 C 库要求注册回调时，很多人第一反应是把一个普通 Go 函数“转成函数指针”传过去。问题在于，C 编译器和链接器只认识遵循 C ABI 的符号，普通 Go 函数既不是 C 声明里的函数，也不是可直接交给 C 的函数指针。//export 的作用，就是让 cgo 为指定 Go 函数生成 C 可见的声明与包装入口，使 C 代码能通过这个入口进入 Go 运行时。

回调前先导出 Go 函数，不是为了改变函数的可见性修饰符，而是为了建立一条符合 C ABI、同时受 Go 运行时接管的跨语言入口。

先分清：普通 Go 函数不等于 C 回调地址

假设第三方 C 库提供如下注册接口：

typedef void (*event_cb)(uintptr_t user_data, int code);
void library_set_callback(event_cb cb, uintptr_t user_data);

这里的 event_cb 是 C 调用约定下的函数指针。Go 里的 func(code int) 是 Go 运行时管理的函数值，两者的参数布局、调用约定、栈管理和运行时进入方式都不能靠一次强制类型转换解决。

官方 cgo 文档还明确指出，Go 代码目前不能直接调用 C 函数指针；通常需要一个 C 包装函数完成间接调用。反过来让 C 调用 Go，同样需要 cgo 生成边界代码，而不是把普通 Go 函数地址暴露出去。

//export 真正补上的是什么

导出函数的最小形态如下。//export 必须紧挨着函数声明，后面的名字要与函数名一致：

package main

/*
#include 
void register_go_callback(uintptr_t user_data);
*/
import "C"

import "runtime/cgo"

//export goOnEvent
func goOnEvent(userData C.uintptr_t, code C.int) {
	h := cgo.Handle(userData)
	state := h.Value().(*State)
	state.OnEvent(int(code))
}

处理这个文件时，cgo 会生成 _cgo_export.h，里面含有 C 侧可用的 goOnEvent 声明，并生成负责跨越运行时边界的包装代码。C 代码调用的是这个 C ABI 入口；入口再把参数交给真正的 Go 函数。

这也解释了为什么只在 Go 包里把函数名改成大写并不够。Go 的导出规则解决的是 Go 包之间的标识符可见性；//export 解决的是 C 世界里是否存在可声明、可链接、可调用的入口。

把函数指针注册留在 C 桥接层

为了避免在 Go 侧直接处理 C 函数指针，可以把第三方库的注册动作放进同包的 C 文件。比如 bridge.c：

#include 
#include "_cgo_export.h"
#include "vendor_library.h"

void register_go_callback(uintptr_t user_data) {
    library_set_callback(goOnEvent, user_data);
}

Go 侧只调用普通的 C 包装函数：

func start(state *State) cgo.Handle {
	h := cgo.NewHandle(state)
	C.register_go_callback(C.uintptr_t(h))
	return h
}

这样每层只做自己擅长的事：第三方库保存 C 函数指针，桥接层引用 cgo 生成的导出符号，Go 代码管理业务对象。出现链接错误时，也能沿着“库声明—桥接文件—生成头文件—导出函数”逐层检查。

上下文不要塞 Go 指针，传一个句柄令牌

回调往往不只需要一个事件码，还需要找到对应的 Go 对象。不要把 *State 强转成 void* 让 C 长期保存。Go 垃圾回收器需要掌握 Go 指针的位置，而 C 内存长期持有未固定的 Go 指针会破坏这条约束。

runtime/cgo.Handle 提供了更稳妥的做法：Go 保存真实值，C 只保存一个可往返传递的整数令牌。回调进入 Go 后，再用 Value 取回对象。

生命周期要与 C 库的注销动作配对。先让库停止产生新回调，等待在途回调结束，再调用 Delete：

func stop(h cgo.Handle) {
	C.library_clear_callback()
	// 若库可能并发回调，这里还要按其 API 等待回调彻底退出。
	h.Delete()
}

如果先删除句柄，而 C 仍可能拿旧令牌回调，Value 会面对已经失效的句柄。若永不删除，Go 对象又会被句柄持续保留，形成资源泄漏。

三个最容易踩中的边界

1. 在带 //export 的 preamble 里写 C 定义

官方文档说明，使用 //export 时，该 Go 文件的 preamble 会被复制到两个不同的 C 输出文件，因此其中只能放声明，不能放函数或变量定义。否则常见结果是链接阶段出现重复符号。把实现放进独立的 .c 文件即可。

2. 导出签名用了 C 无法映射的 Go 类型

不是所有 Go 类型都适合作为导出函数参数。Go struct 和数组不能直接映射为导出接口；需要改成 C struct、C 指针、整数句柄或明确的字节缓冲区。字符串和切片还涉及 Go 指针及生命周期，不能让 C 在调用结束后继续保存。

3. 把导出理解成线程安全保证

cgo 包装入口负责把控制权安全交回 Go 运行时，但不会替业务对象自动加锁。若 C 库会从多个原生线程并发触发回调，State 仍要使用互斥锁、原子操作或消息队列保护；若库要求回调必须返回得很快，也应把耗时工作投递给 Go 侧工作协程。

排查时按这条边界链检查

• 编译期找不到符号：检查 //export 是否紧邻函数、名字是否一致、文件是否导入了 C。
• C 编译器看不到声明：检查桥接 C 文件是否包含 _cgo_export.h，参数类型是否一致。
• 链接阶段重复定义：检查带 //export 的 Go 文件 preamble 是否误放了 C 实现。
• 运行时偶发崩溃：检查 C 是否保存了 Go 指针、句柄是否过早删除、注销后是否还有在途回调。
• 数据竞争：检查第三方库的回调线程模型，并对 Go 状态实施同步。

结论

cgo 回调先导出 Go 函数，核心原因是 C 需要一个真正符合 C ABI 的可调用符号，而 Go 运行时也需要一个受控入口完成跨边界切换。最稳妥的组合通常是：//export 提供入口，独立 C 桥接文件负责注册函数指针，runtime/cgo.Handle 负责传递上下文，注销后再释放句柄。

相关规则可查阅 cmd/cgo 官方文档 与 runtime/cgo.Handle 官方文档。

常见问题

Go 函数名大写后，C 就能调用吗？

不能。大写只影响 Go 包级可见性；C 仍需要 //export 生成的 C ABI 声明和包装入口。

可以把普通 Go 函数强转成 unsafe.Pointer 传给 C 吗？

不应该。Go 函数值不是可移植的 C 函数指针，这种转换绕不开调用约定和运行时边界。

每个回调都要写一个 C 包装函数吗？

导出入口由 cgo 生成；如果第三方库要求注册函数指针，通常还会写一个很薄的 C 桥接函数完成注册。是否需要多个桥接函数取决于库的接口形态。

cgo.Handle 什么时候 Delete？

在 C 库已注销回调、不会再产生新调用，并且所有在途回调都结束后删除。过早删除会留下失效令牌，过晚或不删除会延长 Go 值的生命周期。