使用 cgo 調用 C 代碼

使用 cgo 調用 C 代碼

cgo 是用來為 C 函數創建 Go 綁定的工具。諸如此類的工具都叫作外部函數接口（FFI）。
其他的工具還有，比如SWIG（sig.org）是另一個工具，它提供了更加復雜的特性用來集成C++的類，這個不講。

使用cgo的場景

如果一個程序已經有現成的C語言的實現，但是還沒有Go語言的實現的時候，那沒有一下3種選擇：

1. 如果是一個比較小的C語言庫，可以使用純 Go 語言來移植它（重新實現一遍）。
2. 如果性能不是很關鍵，可以用 os/exec 包以輔助子進程的方式來調用C程序。
3. 當需要使用復雜而且性能要求高的底層C接口時，就是使用cgo的場景了

簡單說就是，如果是簡單的實現，那么就再造一個Go語言的輪子。如果性能要求不高，可以直接通過系統來調用這個程序。只有不想重新造輪子又不想間接的通過系統來調用的時候，就需要用到 cgo 了。

bzip2 壓縮程序正是這樣的一個情況。接下來就要使用 cgo 來構建一個簡單的數據壓縮程序。
標準庫的 compress/... 子包中提供了流行壓縮算法的壓縮器和解壓縮器，包括流行的LZW壓縮算法（Unix的compress命令用的算法）和DEFLATE壓縮算法（GNU gzip命令用的算法）。這些包中的 API 有些許的不同，但都提供一個對 io.Writer 的封裝用來對寫入的數據進行壓縮，并且還有一個對 io.Reader 的封裝，在讀取數據的同時進行壓縮。例如：

package gzip // compress/gzip
func NewWriter(w io.Writer) io.WriteCloser
func NewReader(r io.Reader) (io.ReadCloser, error)

bzip2 算法基于優雅的 Burrows-Wheeler 變換，它和 gzip 相比速度要慢但是壓縮比更高。標準庫的 compress/bzip2 提供了 bzip2 的解壓縮器，但是目前還沒有提供壓縮功能。從頭開始實現這個壓縮算法比較麻煩，而且 http://bzip.org 已經有現成的libbzip2的開源實現了，這是一個文檔完善且高性能的開源 C 語言實現。

要使用C語言的libbzip2包，需要先構建一個bz_stream結構體，這個結構體包含輸入和輸出緩沖區，以及三個C函數：

• BZ2_bzCompressInit: 初始化緩存，分配流的緩沖區
• BZ2_bzCompress: 將輸入緩存的數據壓縮到輸出緩存
• BZ2_bzCompressEnd: 釋放不需要的緩存

C代碼

可以在Go代碼中直接調用BZ2_bzCompressInit和BZ2_bzCompressEnd。
但是對于BZ2_bzCompress，我們將定義一個C語言的包裝函數，用它完成真正的工作。下面是C代碼，和其他Go文件放在同一個包下：

// bzip 包中的文件 bzip2.c
// 對 libbzip2 的簡單包裝，適合 cgo 使用
#include <bzlib.h>

int bz2compress(bz_stream *s, int action,
                char *in, unsigned *inlen, char *out, unsigned *outlen) {
  s->next_in = in;
  s->avail_in = *inlen;
  s->next_out = out;
  s->avail_out = *outlen;
  int r = BZ2_bzCompress(s, action);
  *inlen -= s->avail_in;
  *outlen -= s->avail_out;
  s->next_in = s->next_out = NULL;
  return r;
}

安裝gcc
可能會出現如下的錯誤提示：

exec: "gcc": executable file not found in %PATH%

這個應該是缺少gcc編譯器，所以需要安裝配置好。在Windows系統上可能要麻煩一點，這個問題可以去看下一章節。不過即使Windows上解決了gcc的依賴，但還是沒解決在Windows上安裝bzip2。這個不折騰了，所以這個示例還是需要Linux系統。

cgo注釋

然后是Go代碼，這里只是源碼文件開頭的部分，第一部分如下所示。
聲明 import "C" 很特別， 并沒有這樣的一個包，但是這會讓編譯程序在編譯之前先運行cgo工具：

// bzip 包中的文件 bzip2.go 的第一部分

// 包 bzip 封裝了一個使用 bzip2 壓縮算法的 writer (bzip.org).
package bzip

/*
#cgo CFLAGS: -I/usr/include
#cgo LDFLAGS: -L/usr/lib -lbz2
#include <bzlib.h>
#include <stdlib.h>
bz_stream* bz2alloc() { return calloc(1, sizeof(bz_stream)); }
int bz2compress(bz_stream *s, int action,
                char *in, unsigned *inlen, char *out, unsigned *outlen);
void bz2free(bz_stream* s) { free(s); }
*/
import "C"

import (
    "io"
    "unsafe"
)

type writer struct {
    w      io.Writer // 基本輸出流
    stream *C.bz_stream
    outbuf [64 * 1024]byte
}

// NewWriter 對于 bzip2 壓縮的流返回一個 writer
func NewWriter(out io.Writer) io.WriteCloser {
    const blockSize = 9
    const verbosity = 0
    const workFactor = 30
    w := &writer{w: out, stream: C.bz2alloc()}
    C.BZ2_bzCompressInit(w.stream, blockSize, verbosity, workFactor)
    return w
}

在預處理過程中，cgo 產生一個臨時包，這個包里包含了所有C語言的函數和類型對應的Go語言聲明。例如 C.bz_stream 和 C.BZ2_bzCompressInit。cgo 工具通過以一種特殊的方式調用C編譯器來發現在Go源文件中 import "C" 聲明之前的注釋中包含的C頭文件中的內容。

在cgo注釋中還可以包含 #cgo 指令，用來指定C工具鏈中其他的選項。CFLAGS 和 LDFLAGS 分別對應傳給C語言編譯器的編譯參數和鏈接器參數，使它們可以從特定目錄找到bzlib.h頭文件和libbz2.a庫文件。這個例子假定已經在 /usr 目錄成功安裝了bzip2庫。根據個人的安裝情況，可以修改或者刪除這些標記。（這里還有一個純C生成的cgo綁定，不依賴bzip2靜態庫和操作系統的具體環境，具體訪問github： https://github.com/chai2010/bzip2 ，這里就順帶提一下現在有更方便的實現方式了）

NewWriter 調用C函數 BZ2_bzCompressInit 來初始化流的緩沖區。在 writer 結構體中還包含一個額外的緩沖區用來耗盡解壓縮器的輸出緩沖區。

Write方法

下面所示的 Write 方法將未解壓的數據寫入壓縮器中，然后在一個循環中調用 bz2compress 函數，直到所有的數據壓縮完畢。Go程序可以訪問C的類型（比如 bz_stream、char 和 uint），C的函數（比如 bz2compress），甚至是類似C的預處理宏的對象（比如 BZ_RUN），這些都通過 C.x 的方式來訪問。即使類型 C.unit 和 Go 的 uint 長度相同，它們的類型也是不同的：

// bzip 包中的文件 bzip2.go 的第二部分

func (w *writer) Write(data []byte) (int, error) {
    if w.stream == nil {
        panic("closed")
    }
    var total int // 寫入的未壓縮字節數

    for len(data) > 0 {
        inlen, outlen := C.uint(len(data)), C.uint(cap(w.outbuf))
        C.bz2compress(w.stream, C.BZ_RUN,
            (*C.char)(unsafe.Pointer(&data[0])), &inlen,
            (*C.char)(unsafe.Pointer(&w.outbuf)), &outlen)
        total += int(inlen)
        data = data[inlen:]
        if _, err := w.w.Write(w.outbuf[:outlen]); err != nil {
            return total, err
        }
    }
    return total, nil
}

每一次的迭代首先計算傳說數據 data 剩余的長度以及輸出緩沖 w.outbuf 的容量。然后把這兩個值的地址以及 data 和 w.outbuf 的地址都傳遞給 bz2compress 函數。兩個長度信息傳地址而不傳值，這樣C函數就可以更新這兩個值。這兩個值記錄的分別是已壓縮的數據和壓縮后數據的大小。然后把每塊壓縮后的數據寫入底層的 io.Writer（w.w.Write方法）。

Close方法

Close方法和Write方法結構類似，通過一個循環將剩余的壓縮后的數據從輸出緩沖區寫入底層：

// bzip 包中的文件 bzip2.go 的第三部分

// Close 方法清空壓縮的數據并關閉流
// 它不會關閉底層的 io.Writer
func (w *writer) Close() error {
    if w.stream == nil {
        panic("closed")
    }
    defer func() {
        C.BZ2_bzCompressEnd(w.stream)
        C.bz2free(w.stream)
        w.stream = nil
    }()
    for {
        inlen, outlen := C.uint(0), C.uint(cap(w.outbuf))
        r := C.bz2compress(w.stream, C.BZ_FINISH, nil, &inlen,
            (*C.char)(unsafe.Pointer(&w.outbuf)), &outlen)
        if _, err := w.w.Write(w.outbuf[:outlen]); err != nil {
            return err
        }
        if r == C.BZ_STREAM_END {
            return nil
        }
    }
}

壓縮完成后，Close 方法最后會調用 C.BZ2_bzCompressEnd 來釋放流緩沖區，這寫語句寫在 defer 中來確保所有路徑返回后都會釋放資源。這個時候，w.stream 指針就不能安全地解引用了，要把它設置為 nil，并且在方法調用的開頭添加顯式的 nil 檢查。這樣如果用戶在 Close 之后錯誤地調用方法，程序就會panic。

使用bzip包

下面的程序，使用上面的程序包實現bzip2壓縮命令。用起來和很多UNIX系統上面的 bzip2 命令相似：

// bzipper 讀取輸入、使用 bzip2 壓縮然后輸出數據
package main

import (
    "io"
    "log"
    "os"

    "gopl/bzip"
)

func main() {
    w := bzip.NewWriter(os.Stdout)
    if _, err := io.Copy(w, os.Stdin); err != nil {
        log.Fatalf("bzipper: %v\n", err)
    }
    if err := w.Close(); err != nil {
        log.Fatalf("bzipper: close: %v\n", err)
    }
}

總結

這里演示了如何將C庫鏈接進Go程序中。（反過來，可以將Go程序編譯為靜態庫然后鏈接進C程序中，也可以編譯為動態庫通過C程序來加載和共享）
另外還有一些別的問題。

沒有bzip2庫
這里的例子是假設已經安裝了 bzip2 庫。如果是安裝位置不對，可以修改 #cgo 來解決。另外，也有人提供了不用依賴本機上的 bzip2 庫的實現。
這里有一個從純C代碼生成的cgo綁定，不依賴bzip2靜態庫和操作系統的具體環境，具體請訪問 https://github.com/chai2010/bzip2

并發安全問題
上面的實現中，結構體 writer 不是并發安全的。并且并發調用 Close 和 Write 也會導致C代碼崩潰。這個問題可以用加鎖的方式來避免，使用 sync.Mutex 可以保證 bzip2.writer 在多個goroutines中被并發調用是安全的。

os/exec 包的實現
開篇提到了還有一種實現方式：用 os/exec 包以輔助子進程的方式來調用C程序。
可以使用 os/exec 包將 /bin/bzip2 命令作為一個子進程執行。實現一個純Go的 bzip.NewWriter 來替代原來的實現。這樣就是一個純Go的實現，不需要C言語的基礎。不過雖然是純Go的實現，但還是要依賴本機能夠運行 /bin/bzaip2 命令的。

安裝cgo環境

MinGW（Minimalist GNU For Windows），是個精簡的Windows平臺C/C++、ADA及Fortran編譯器，相比Cygwin而言，體積要小很多，使用較為方便。
實際上也沒那么方便...

錯誤信息

首先，會遇到下面的報錯：

exec: "gcc": executable file not found in %PATH%

這是因為缺少gcc編譯器。

另外如果裝好了，可能還會遇到這個問題：

cc1.exe: sorry, unimplemented: 64-bit mode not compiled in

這是因為需要安裝一個64位的版本。

最后還會有一個小問題的報錯，類似下面這樣：

.\main.go:9:45: could not determine kind of name for C.FLT_MAX

看這個報錯的內容是我們的代碼的問題。其實就是 cgo 注釋必須緊挨著 import "C"，中間不能有空行。

下載安裝

可以去這里下載：
https://sourceforge.net/projects/mingw-w64/
不過這只是一個在線安裝程序。應該是國外的資源，在線安裝無法成功。
還可以直接去下載編譯好的版本，資源都在頁面的Files分頁里查找。因為有一些編譯的選項來適配各種系統和版本，下載了下面路徑下的文件：

Home/Toolchains targetting Win64/Personal Builds/mingw-builds/8.1.0/threads-win32/seh/

文件名是這個：x86_64-8.1.0-release-win32-seh-rt_v6-rev0.7z
具體的下載地址是：
https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/mingw-builds/7.3.0/threads-win32/seh/x86_64-7.3.0-release-win32-seh-rt_v5-rev0.7z
因為是編譯好的版本，無需安裝直接解壓就可以了。

設置環境變量

解壓后放在系統的某個目錄下，比如 gcc.exe 這個文件的路徑是這個：D:\MinGW\bin\gcc.exe。下面就按這個路徑來設置環境變量。
我的電腦->屬性->高級系統設置，在“高級”分頁下的“環境變量...”里就可以設置環境變量。
添加一條環境變量：

然后在已有的環境變量 Path 里添加一項 %MinGW%\bin，到此設置完成。

運行一個簡單cgo程序

下面是一段簡單的cgo代碼：

package main

// #include <float.h>
import "C"
import "fmt"

func main() {
    fmt.Println("Max float value of float is", C.FLT_MAX)
}

就像普通的Go程序那樣編譯運行就好了。