从 C 代码调用 Go 函数：一份详细教程

本文档旨在详细介绍如何在 C 代码中调用 Go 函数。由于 CGO 的复杂性，这种跨语言调用可能会让人感到困惑。本文将通过代码示例，逐步讲解如何实现从 C 到 Go 的函数回调，并提供一个更高级的示例，展示如何在 C 函数执行过程中向 Go 应用发送进度通知。

基础：从 C 调用 Go 函数

要从 C 代码调用 Go 函数，需要利用 CGO (C Go Interface) 的特性。关键在于使用 //export 注释标记 Go 函数，并使用 extern 关键字在 C 代码中声明这些函数。

示例：简单的加法运算

以下代码展示了一个简单的示例，其中 C 代码调用 Go 函数执行加法运算。

package foo

// extern int goCallbackHandler(int, int);
//
// static int doAdd(int a, int b) {
//     return goCallbackHandler(a, b);
// }
import "C"

//export goCallbackHandler
func goCallbackHandler(a, b C.int) C.int {
    return a + b
}

// MyAdd 是一个公共函数，可以从包外部调用。
// 它将参数转发到 C.doAdd()，后者又将它们转发回
// goCallbackHandler()。这个函数执行加法运算并返回结果。
func MyAdd(a, b int) int {
   return int( C.doAdd( C.int(a), C.int(b)) )
}

在这个例子中：

//export goCallbackHandler 注释告诉 CGO 将 goCallbackHandler 函数导出为 C 可调用的函数。
extern int goCallbackHandler(int, int); 在 C 代码中声明了 goCallbackHandler 函数。
C.doAdd 是一个 C 函数，它调用了 Go 函数 goCallbackHandler。
MyAdd 是一个 Go 函数，它调用 C 函数 C.doAdd，从而间接调用 Go 函数 goCallbackHandler。

调用的顺序如下：

foo.MyAdd(a, b) ->
  C.doAdd(a, b) ->
    C.goCallbackHandler(a, b) ->
      foo.goCallbackHandler(a, b)

关键点:

必须使用 //export 注释标记 Go 回调函数。
必须在 C 代码中使用 extern 声明 Go 回调函数。
回调函数必须在 Go 包内部定义。

高级：传递用户自定义回调函数

为了允许用户提供自定义回调函数，可以将用户自定义的处理函数（只是一个普通的 Go 函数）作为参数传递到 C 端，作为 void*。然后，我们的包中的回调处理函数接收到这个 void*，并调用用户提供的函数。

示例：文件处理进度回调

假设有一个 C 函数从 USB 设备读取文件列表，这是一个耗时操作。为了通知应用程序进度，我们可以传递一个函数指针，该指针在读取过程中被调用。

首先，定义一个 ProgressHandler 类型：

type ProgressHandler func(current, total uint64, userdata interface{}) int

然后，编写 C 和 Go 的接口代码：

package foo

// #include 
// extern int goProgressCB(uint64_t current, uint64_t total, void* userdata);
//
// static int goGetFiles(some_t* handle, void* userdata) {
//    return somelib_get_files(handle, goProgressCB, userdata);
// }
import "C"
import "unsafe"

// ProgressHandler 定义用户提供的进度处理函数的签名
type ProgressHandler func(current, total uint64, userdata interface{}) int

// progressRequest 是一个内部类型，用于封装用户的回调函数和用户数据。
// 实际上，我们将把这个类型的实例发送到 C 代码。
type progressRequest struct {
   f ProgressHandler  // 用户的函数指针
   d interface{}      // 用户的用户数据
}

//export goProgressCB
func goProgressCB(current, total C.uint64_t, userdata unsafe.Pointer) C.int {
    // 这是一个从 C 代码（通过耗时的 C.somelib_get_files() 函数）调用的函数。
    // userdata 值包含 *progressRequest 的实例。我们解包它并使用它的值来调用
    // 用户提供的实际函数。
    req := (*progressRequest)(userdata)

    // 使用我们的参数和用户的用户数据值调用 req.f。
    return C.int( req.f( uint64(current), uint64(total), req.d ) )
}

// GetFiles 是一个公共函数，由用户调用，
// 它接收 C 库需要的句柄、函数指针和可选的用户定义的数据结构。
func GetFiles(h *Handle, pf ProgressHandler, userdata interface{}) int {
   // 我们不直接调用外部 C 库，而是调用我们的 C 包装器。
   // 我们将句柄和 progressRequest 的实例传递给它。

   req := unsafe.Pointer(&progressRequest{ pf, userdata })
   return int(C.goGetFiles( (*C.some_t)(h), req ))
}

在这个例子中：

goGetFiles 是一个 C 包装器函数，它调用实际的 C 库函数 somelib_get_files。
goProgressCB 是一个 Go 回调函数，它被 C 代码调用。
progressRequest 结构体用于封装用户的回调函数和用户数据。
GetFiles 是一个公共函数，用户可以使用它来调用 C 库函数并传递回调函数。

用户代码如下：

package main

import (
    "foo"
    "fmt"
)

func main() {
    handle := SomeInitStuff()

    // 调用 GetFiles。将我们的进度处理函数和一些
    // 任意用户数据（也可以是 nil）传递给它。
    ret := foo.GetFiles( handle, myProgress, "Callbacks rock!" )

    ....
}

// myProgress 是我们的进度处理函数。执行一些有用的操作，例如显示
// 进度百分比。
func myProgress(current, total uint64, userdata interface{}) int {
    fc := float64(current)
    ft := float64(total) * 0.01

    // 打印我们完成了多少。
    // 例如：500 / 1000 (50.00%)
    // 为了安全起见，在它前面加上我们的用户数据值，我们
    // 将其作为 "Callbacks rock!" 提供。
    fmt.Printf("%s: %d / %d (%3.2f%%)\n", userdata.(string), current, total, fc / ft)
    return 0
}

调用的顺序如下：

foo.GetFiles(....) ->
  C.goGetFiles(...) ->
    C.somelib_get_files(..) ->
      C.goProgressCB(...) ->
        foo.goProgressCB(...) ->
           main.myProgress(...)

注意事项：