它将 JS 绑定到您的 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
这样的好名字会被重命名为某种内容,用于在函数名称中对链接器进行签名编码。因此,我们无法再使用其名称查找函数。
进入 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 公开函数。
如需编译此文件,我们可以使用与上一篇文章中相同的设置(或者,如果需要,也可以使用相同的 Docker 映像)。为了使用 embind,我们添加了 --bind
标志:
$ emcc --bind -O3 add.cpp
现在,只需创建一个用于加载我们新创建的 wasm 模块的 HTML 文件即可:
<script src="/a.out.js"></script>
<script>
Module.onRuntimeInitialized = _ => {
console.log(Module.add(1, 2.3));
console.log(Module.exclaim("hello world"));
};
</script>
如您所见,我们不再使用 cwrap()
。这项功能“开箱即用”但更重要的是,我们不必担心手动复制内存块以使字符串正常运行!embind 会免费为您提供此功能,以及类型检查:
这非常棒,因为我们可以尽早发现一些错误,而无需处理偶尔非常棘手的 Wasm 错误。
对象
许多 JavaScript 构造函数和函数都使用 options 对象。这在 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 的文档。请注意,使用 embind 后,在压缩为 gzip 格式时,您的 wasm 模块和 JavaScript 粘合代码的大小最多会增加 11k,尤其是在小模块上。如果您的 Wasm 表面非常小,则 embind 在生产环境中的费用可能会超过其价值!不过,你一定要试一试