Emscripten 的魔法

這會將 JS 繫結至 wasm！

Surma

在上一篇 wasm 文章中，我曾提到如何將 C 程式庫編譯為 wasm，以便在網路上使用。對我和許多讀者來說，最明顯的缺點是，您必須手動宣告要使用的 wasm 模組函式，這麼做既粗糙又不方便。為方便您瞭解，以下是所指的程式碼片段：

const api = {
    version: Module.cwrap('version', 'number', []),
    create_buffer: Module.cwrap('create_buffer', 'number', ['number', 'number']),
    destroy_buffer: Module.cwrap('destroy_buffer', '', ['number']),
};

我們在這裡宣告標示為 EMSCRIPTEN_KEEPALIVE 的函式名稱、傳回類型，以及參數類型。之後，我們可以使用 api 物件的這些方法來叫用這些函式。不過，以這種方式使用 wasm 並不支援字串，因此您必須手動移動記憶體區塊，這使得許多程式庫 API 難以使用。有沒有更好的方法？為什麼會有人來找我，否則這篇文章又說明什麼呢？

C++ 名稱轉換

雖然開發人員經驗足以讓您建構可協助這些繫結的工具，但其實還有更迫切的原因：當您編譯 C 或 C++ 程式碼時，每個檔案都會個別編譯。接著，連結器會負責將所有這些稱為物件檔案的檔案合併，並將其轉換為 WASM 檔案。在 C 中，函式的名稱仍可供連結器使用，您只需要呼叫 C 函式的名稱，我們會將名稱做為字串提供給 cwrap()。

另一方面，C++ 支援函式超載，也就是說，只要簽名不同 (例如不同類型的參數)，您就可以多次實作相同的函式。在編譯器層級，像 add 這樣的好名稱會破壞形式，會對連結器函式名稱中的簽章進行編碼。因此，我們無法再以名稱查詢函式。

注意： 您可以在為函式加上 extern "C" 註解後，防止編譯器破壞函式名稱。

輸入 embind

embind 是 Emscripten 工具鍊的一部分，可提供一系列 C++ 巨集，讓您為 C++ 程式碼加上註解。您可以在 JavaScript 中宣告自己打算使用的函式、列舉、類別或值類型。讓我們先使用一些簡單的函式來簡單說明：

#include <emscripten/bind.h>

using namespace emscripten;

double add(double a, double b) {
    return a + b;
}

std::string exclaim(std::string message) {
    return message + "!";
}

EMSCRIPTEN_BINDINGS(my_module) {
    function("add", &add);
    function("exclaim", &exclaim);
}

與先前的文章相比，我們不再納入 emscripten.h，因為我們再也不必使用 EMSCRIPTEN_KEEPALIVE 為函式加上註解。而是改為提供 EMSCRIPTEN_BINDINGS 區段，並在其中列出要向 JavaScript 公開函式的名稱。

注意：EMSCRIPTEN_BINDINGS 巨集的參數主要用於避免大型專案中的名稱衝突。

如要編譯這個檔案，我們可以使用與上一篇文章相同的設定 (或 Docker 映像檔)。如要使用 embind，請新增 --bind 標記：

$ emcc --bind -O3 add.cpp

接下來，我們只需要製作 HTML 檔案，載入我們新建的 wasm 模組：

<script src="/a.out.js"></script>
<script>
Module.onRuntimeInitialized = _ => {
    console.log(Module.add(1, 2.3));
    console.log(Module.exclaim("hello world"));
};
</script>

注意： 如果方便的話，我編寫了相同的 C++ 模組，不會說明這個模組可為您執行多大的工作。

如您所見，我們不再使用 cwrap()。這項功能開箱即可使用。更重要的是，我們不必擔心要手動複製記憶體區塊才能讓字串運作！embind 會免費提供這項功能，並進行型別檢查：

這非常棒，因為我們可以及早發現某些錯誤，而不用處理有時相當難以處理的 wasm 錯誤。

物件

許多 JavaScript 建構函式和函式都會使用選項物件。這是 JavaScript 中不錯的模式，但在 WASM 中手動實現此模式非常繁瑣。embind 在這裡也能提供協助！

舉例來說，我想出這個處理字串的「極度」實用的 C++ 函式，而且我急迫想要在網路上使用。我的方法如下：

#include <emscripten/bind.h>
#include <algorithm>

using namespace emscripten;

struct ProcessMessageOpts {
    bool reverse;
    bool exclaim;
    int repeat;
};

std::string processMessage(std::string message, ProcessMessageOpts opts) {
    std::string copy = std::string(message);
    if(opts.reverse) {
    std::reverse(copy.begin(), copy.end());
    }
    if(opts.exclaim) {
    copy += "!";
    }
    std::string acc = std::string("");
    for(int i = 0; i < opts.repeat; i++) {
    acc += copy;
    }
    return acc;
}

EMSCRIPTEN_BINDINGS(my_module) {
    value_object<ProcessMessageOpts>("ProcessMessageOpts")
    .field("reverse", &ProcessMessageOpts::reverse)
    .field("exclaim", &ProcessMessageOpts::exclaim)
    .field("repeat", &ProcessMessageOpts::repeat);

    function("processMessage", &processMessage);
}

我正在為 processMessage() 函式的選項定義結構體。在 EMSCRIPTEN_BINDINGS 區塊中，我可以使用 value_object，讓 JavaScript 將這個 C++ 值視為物件。如果偏好使用這個 C++ 值做為陣列，我也可以使用 value_array。我也會繫結 processMessage() 函式，其餘部分則是 embind 魔法。我現在可以從 JavaScript 呼叫 processMessage() 函式，而不需要任何固定程式碼：

console.log(Module.processMessage(
    "hello world",
    {
    reverse: false,
    exclaim: true,
    repeat: 3
    }
)); // Prints "hello world!hello world!hello world!"

類別

為了完整執行清醒，我也應該說明 embind 如何讓您公開整個類別，進而帶來許多與 ES6 類別的協同作業。您現在應該可以開始看到模式了：

#include <emscripten/bind.h>
#include <algorithm>

using namespace emscripten;

class Counter {
public:
    int counter;

    Counter(int init) :
    counter(init) {
    }

    void increase() {
    counter++;
    }

    int squareCounter() {
    return counter * counter;
    }
};

EMSCRIPTEN_BINDINGS(my_module) {
    class_<Counter>("Counter")
    .constructor<int>()
    .function("increase", &Counter::increase)
    .function("squareCounter", &Counter::squareCounter)
    .property("counter", &Counter::counter);
}

在 JavaScript 上，這幾乎就像是原生類別：

<script src="/a.out.js"></script>
<script>
Module.onRuntimeInitialized = _ => {
    const c = new Module.Counter(22);
    console.log(c.counter); // prints 22
    c.increase();
    console.log(c.counter); // prints 23
    console.log(c.squareCounter()); // prints 529
};
</script>

那 C 呢？

embind 是為 C++ 編寫，且只能用於 C++ 檔案，但這並不表示您無法連結 C 檔案！如要混用 C 和 C++，您只需將輸入檔案分為兩個群組：一個用於 C 檔案，另一個用於 C++ 檔案，並增強 emcc 的 CLI 標記，如下所示：

$ emcc --bind -O3 --std=c++11 a_c_file.c another_c_file.c -x c++ your_cpp_file.cpp

結論

embind 在使用 wasm 和 C/C++ 時，可大幅改善開發人員體驗。本文並未涵蓋所有優惠活動選項。如有興趣，建議您繼續參閱 embind 的說明文件。請注意，使用 embind 時，在 gzip 時，您的 wasm 模組和 JavaScript 黏著劑程式碼會變得更大，最多可達 11k，特別是在小型模組上。如果您只有極小的 Wam 表面，繫結成本可能會高於在實際工作環境中的價值！不過，您還是應該試試看。