自定义外部引用

    下面的教程是对 WasmEdge 中的 externref 示例的总结。

    Wasm 文件应该包含接受 externref 的 host 函数导入。以为例（WAT是相对应的文本格式）。

    你可以通过 在线实时工具将 wat 转换为 wasm。注意页面上的 reference types 复选框必须勾选。

    在执行 Wasm 执行前，host 模块必须实现以及在 WasmEdge 中注册。假设下面的代码保存为 main.c：

    1. #include <wasmedge/wasmedge.h>
    3. #include <stdio.h>
    5. uint32_t SquareFunc(uint32_t A) { return A * A; }
    6. uint32_t AddFunc(uint32_t A, uint32_t B) { return A + B; }
    7. uint32_t MulFunc(uint32_t A, uint32_t B) { return A * B; }
    9. // Host 函数通过外部引用调用 `SquareFunc`
    10. WasmEdge_Result ExternSquare(void *Data, WasmEdge_MemoryInstanceContext *MemCxt,
    11.                              const WasmEdge_Value *In, WasmEdge_Value *Out) {
    12.   // 函数类型: {externref, i32} -> {i32}
    13.   uint32_t (*Func)(uint32_t) = WasmEdge_ValueGetExternRef(In[0]);
    14.   uint32_t C = Func(WasmEdge_ValueGetI32(In[1]));
    15.   Out[0] = WasmEdge_ValueGenI32(C);
    16.   return WasmEdge_Result_Success;
    17. }
    19. // Host 函数通过外部引用调用 `AddFunc`
    20. WasmEdge_Result ExternAdd(void *Data, WasmEdge_MemoryInstanceContext *MemCxt,
    21.                           const WasmEdge_Value *In, WasmEdge_Value *Out) {
    22.   // 函数类型: {externref, i32, i32} -> {i32}
    23.   uint32_t (*Func)(uint32_t, uint32_t) = WasmEdge_ValueGetExternRef(In[0]);
    24.   uint32_t C = Func(WasmEdge_ValueGetI32(In[1]), WasmEdge_ValueGetI32(In[2]));
    25.   Out[0] = WasmEdge_ValueGenI32(C);
    26.   return WasmEdge_Result_Success;
    27. }
    29. // host 函数通过外部引用调用 `ExternMul`
    30. WasmEdge_Result ExternMul(void *Data, WasmEdge_MemoryInstanceContext *MemCxt,
    31.                           const WasmEdge_Value *In, WasmEdge_Value *Out) {
    32.   // 函数类型: {externref, i32, i32} -> {i32}
    33.   uint32_t (*Func)(uint32_t, uint32_t) = WasmEdge_ValueGetExternRef(In[0]);
    34.   uint32_t C = Func(WasmEdge_ValueGetI32(In[1]), WasmEdge_ValueGetI32(In[2]));
    35.   Out[0] = WasmEdge_ValueGenI32(C);
    36.   return WasmEdge_Result_Success;
    37. }
    39. // 创建“extern_module”引入对象的辅助函数。
    40. WasmEdge_ImportObjectContext *CreateExternModule() {
    41.   WasmEdge_String HostName;
    42.   WasmEdge_FunctionTypeContext *HostFType = NULL;
    43.   WasmEdge_FunctionInstanceContext *HostFunc = NULL;
    44.   enum WasmEdge_ValType P[3], R[1];
    46.   HostName = WasmEdge_StringCreateByCString("extern_module");
    47.   WasmEdge_ImportObjectContext *ImpObj = WasmEdge_ImportObjectCreate(HostName);
    48.   WasmEdge_StringDelete(HostName);
    50.   // 添加 host 函数 "functor_square": {externref, i32} -> {i32}
    51.   P[0] = WasmEdge_ValType_ExternRef;
    52.   P[1] = WasmEdge_ValType_I32;
    53.   R[0] = WasmEdge_ValType_I32;
    54.   HostFType = WasmEdge_FunctionTypeCreate(P, 2, R, 1);
    55.   HostFunc = WasmEdge_FunctionInstanceCreate(HostFType, ExternSquare, NULL, 0);
    56.   WasmEdge_FunctionTypeDelete(HostFType);
    57.   HostName = WasmEdge_StringCreateByCString("functor_square");
    58.   WasmEdge_ImportObjectAddFunction(ImpObj, HostName, HostFunc);
    59.   WasmEdge_StringDelete(HostName);
    61.   // 添加 host 函数 "class_add": {externref, i32, i32} -> {i32}
    62.   P[2] = WasmEdge_ValType_I32;
    63.   HostFType = WasmEdge_FunctionTypeCreate(P, 3, R, 1);
    64.   HostFunc = WasmEdge_FunctionInstanceCreate(HostFType, ExternAdd, NULL, 0);
    65.   WasmEdge_FunctionTypeDelete(HostFType);
    66.   HostName = WasmEdge_StringCreateByCString("class_add");
    67.   WasmEdge_ImportObjectAddFunction(ImpObj, HostName, HostFunc);
    68.   WasmEdge_StringDelete(HostName);
    70.   // 添加 host 函数 "func_mul": {externref, i32, i32} -> {i32}
    71.   HostFType = WasmEdge_FunctionTypeCreate(P, 3, R, 1);
    72.   HostFunc = WasmEdge_FunctionInstanceCreate(HostFType, ExternMul, NULL, 0);
    73.   WasmEdge_FunctionTypeDelete(HostFType);
    74.   HostName = WasmEdge_StringCreateByCString("func_mul");
    75.   WasmEdge_ImportObjectAddFunction(ImpObj, HostName, HostFunc);
    76.   WasmEdge_StringDelete(HostName);
    78.   return ImpObj;
    79. }
    81. int main() {
    82.   WasmEdge_VMContext *VMCxt = WasmEdge_VMCreate(NULL, NULL);
    83.   WasmEdge_ImportObjectContext *ImpObj = CreateExternModule();
    84.   WasmEdge_Value P[3], R[1];
    85.   WasmEdge_String FuncName;
    86.   WasmEdge_Result Res;
    88.   Res = WasmEdge_VMRegisterModuleFromImport(VMCxt, ImpObj);
    89.   if (!WasmEdge_ResultOK(Res)) {
    90.     printf("Import object registration failed\n");
    91.     return EXIT_FAILURE;
    92.   }
    93.   Res = WasmEdge_VMLoadWasmFromFile(VMCxt, "funcs.wasm");
    94.   if (!WasmEdge_ResultOK(Res)) {
    95.     printf("WASM file loading failed\n");
    96.     return EXIT_FAILURE;
    97.   }
    98.   Res = WasmEdge_VMValidate(VMCxt);
    99.   if (!WasmEdge_ResultOK(Res)) {
    100.     printf("WASM validation failed\n");
    101.     return EXIT_FAILURE;
    102.   }
    103.   Res = WasmEdge_VMInstantiate(VMCxt);
    104.     printf("WASM instantiation failed\n");
    105.     return EXIT_FAILURE;
    106.   }
    108.   // 测试用例 1：调用 add -- 1234 + 5678
    109.   P[0] = WasmEdge_ValueGenExternRef(AddFunc);
    110.   P[1] = WasmEdge_ValueGenI32(1234);
    111.   P[2] = WasmEdge_ValueGenI32(5678);
    112.   FuncName = WasmEdge_StringCreateByCString("call_add");
    113.   Res = WasmEdge_VMExecute(VMCxt, FuncName, P, 3, R, 1);
    114.   WasmEdge_StringDelete(FuncName);
    115.   if (WasmEdge_ResultOK(Res)) {
    116.     printf("Test 1 -- `call_add` -- 1234 + 5678 = %d\n",
    117.            WasmEdge_ValueGetI32(R[0]));
    118.   } else {
    119.     printf("Test 1 -- `call_add` -- 1234 + 5678 -- failed\n");
    120.     return EXIT_FAILURE;
    123.   // 测试用例 2：调用 mul -- 789 * 4321
    124.   P[0] = WasmEdge_ValueGenExternRef(MulFunc);
    125.   P[1] = WasmEdge_ValueGenI32(789);
    126.   P[2] = WasmEdge_ValueGenI32(4321);
    127.   FuncName = WasmEdge_StringCreateByCString("call_mul");
    128.   Res = WasmEdge_VMExecute(VMCxt, FuncName, P, 3, R, 1);
    129.   WasmEdge_StringDelete(FuncName);
    130.   if (WasmEdge_ResultOK(Res)) {
    131.     printf("Test 2 -- `call_mul` -- 789 * 4321 = %d\n",
    132.            WasmEdge_ValueGetI32(R[0]));
    133.   } else {
    134.     printf("Test 2 -- `call_mul` -- 789 * 4321 -- failed\n");
    135.     return EXIT_FAILURE;
    136.   }
    138.   // 测试用例 3：调用 square -- 8256^2
    139.   P[0] = WasmEdge_ValueGenExternRef(SquareFunc);
    140.   P[1] = WasmEdge_ValueGenI32(8256);
    141.   FuncName = WasmEdge_StringCreateByCString("call_square");
    142.   Res = WasmEdge_VMExecute(VMCxt, FuncName, P, 2, R, 1);
    143.   if (WasmEdge_ResultOK(Res)) {
    144.     printf("Test 3 -- `call_mul` -- 8256 ^ 2 = %d\n",
    145.            WasmEdge_ValueGetI32(R[0]));
    146.   } else {
    147.     printf("Test 3 -- `call_mul` -- 8256 ^ 2 -- failed\n");
    148.     return EXIT_FAILURE;
    149.   }
    151.   return EXIT_SUCCESS;
    152. }

    1. 安装 WasmEdge 共享库。

      详细信息请参阅安装。

    2. 如上所示准备 WASM 文件和 main.c 源文件。

    3. 编译

      1. gcc main.c -lwasmedge_c
      2. # 或者你可以在 C++ 场景下使用 g++，或者使用 clang。

    4. 运行测试用例

      1. $ ./a.out
      2. Test 1 -- `call_add` -- 1234 + 5678 = 6912
      3. Test 2 -- `call_mul` -- 789 * 4321 = 3409269
      4. Test 3 -- `call_mul` -- 8256 ^ 2 = 68161536
    1. (module
    2.   (type $t0 (func (param externref i32) (result i32)))
    3.   ;; Import a host function which type is {externref i32} -> {i32}
    4.   (import "extern_module" "functor_square" (func $functor_square (type $t0)))
    5.   ;; Wasm function which type is {externref i32} -> {i32} and exported as "call_square"
    6.   (func $call_square (export "call_square") (type $t0) (param $p0 externref) (param $p1 i32) (result i32)
    7.     (call $functor_square (local.get $p0) (local.get $p1))
    8.   )
    9.   (memory $memory (export "memory") 1))

    Wasm 函数 “call_square“ 包含一个 externref 参数，并用这个 externref 调用导入的 host 函数 functor_square。所以，当你调用 Wasm 函数 call_square 并传递对象的引用时，host 函数 functor_square 就能获得该对应引用。

    下面的例子展示了如何在 Wasm 里通过 WasmEdge C API 使用 externref。

    Wasm 代码必须将 externref 传递给想要访问它的 host 函数。以下文的 wat 为例，这是 的其中一部分：

    1. (module
    2.   (type $t0 (func (param externref i32 i32) (result i32)))
    3.   (import "extern_module" "func_mul" (func $func_mul (type $t0)))
    4.   (func $call_mul (export "call_mul") (type $t0) (param $p0 externref) (param $p1 i32) (param $p2 i32) (result i32)
    5.     (call $func_mul (local.get $p0) (local.get $p1) (local.get $p2))
    6.   )
    7.   (memory $memory (export "memory") 1))

    host 函数 extern_module::func_mul 将 externref 作为一个函数指针用来将参数 1 和参数 2 相乘并返回其结果。输出的 Wasm 函数 call_mul 调用 func_mul 并传递 externref 和 2 个数字作为参数。

    要实例化上面的 Wasm 示例，host 函数必须注册到 WasmEdge 中。详见 Host 函数。接受 externref 的 host 函数必须知道原始对象的类型。我们以函数指针为例。

    “MulFunc“ 是一个函数，将作为 externref 传递给 Wasm。在 host 函数 “func_mul“ 中，你可以使用 “WasmEdge_ValueGetExternRef“ API 从包含 externref 的 WasmEdge_Value 中获取指针。

    开发人员可以将带有名称的 host 函数添加到导入对象中。

    1. /* 创建一个导入对象。 */
    2. WasmEdge_String HostName = WasmEdge_StringCreateByCString("extern_module");
    3. WasmEdge_ImportObjectContext *ImpObj = WasmEdge_ImportObjectCreate(HostName);
    4. WasmEdge_StringDelete(HostName);
    6. /* 创建一个函数实例并添加到一个导入对象中。 */
    7. enum WasmEdge_ValType P[3], R[1];
    8. P[0] = WasmEdge_ValType_ExternRef;
    9. P[1] = WasmEdge_ValType_I32;
    10. P[2] = WasmEdge_ValType_I32;
    11. R[0] = WasmEdge_ValType_I32;
    12. WasmEdge_FunctionTypeContext *HostFType = WasmEdge_FunctionTypeCreate(P, 3, R, 1);
    13. WasmEdge_FunctionInstanceContext *HostFunc = WasmEdge_FunctionInstanceCreate(HostFType, ExternFuncMul, NULL, 0);
    14. WasmEdge_FunctionTypeDelete(HostFType);
    15. HostName = WasmEdge_StringCreateByCString("func_mul");
    16. WasmEdge_ImportObjectAddFunction(ImpObj, HostName, HostFunc);
    17. WasmEdge_StringDelete(HostName);
    19. ...

    执行

    以为例（WAT是相对应的文本格式）。假设函数 funcs.wasm 被复制到了当前目录。下面的例子展示了如何在 Wasm 里用 WasmEdge C API 使用 externref。

    1. /* 创建 VM 上下文。 */
    2. WasmEdge_VMContext *VMCxt = WasmEdge_VMCreate(NULL, NULL);
    3. /* 创建包含 host 函数的导入对象上下文。 */
    4. WasmEdge_ImportObjectContext *ImpObj = /* Ignored ... */;
    5. /* 假设 host 函数被添加到上面的导入对象中。 */
    6. WasmEdge_Value P[3], R[1];
    7. WasmEdge_String FuncName;
    8. WasmEdge_Result Res;
    10. /* 将导入对象注册到 VM。 */
    11. Res = WasmEdge_VMRegisterModuleFromImport(VMCxt, ImpObj);
    12. if (!WasmEdge_ResultOK(Res)) {
    13.   printf("Import object registration failed\n");
    14.   return EXIT_FAILURE;
    15. }
    16. /* 从文件中加载 WASM。 */
    17. Res = WasmEdge_VMLoadWasmFromFile(VMCxt, "funcs.wasm");
    18. if (!WasmEdge_ResultOK(Res)) {
    19.   printf("WASM file loading failed\n");
    20.   return EXIT_FAILURE;
    21. }
    22. /* 验证 WASM。 */
    23. if (!WasmEdge_ResultOK(Res)) {
    24.   printf("WASM validation failed\n");
    25.   return EXIT_FAILURE;
    26. }
    27. /* 实例化 WASM 模块。 */
    28. Res = WasmEdge_VMInstantiate(VMCxt);
    29. if (!WasmEdge_ResultOK(Res)) {
    30.   printf("WASM instantiation failed\n");
    32. }
    34. /* 运行 WASM 函数。 */
    35. P[0] = WasmEdge_ValueGenExternRef(AddFunc);
    36. P[1] = WasmEdge_ValueGenI32(1234);
    37. P[2] = WasmEdge_ValueGenI32(5678);
    38. /* 运行 `call_add` 函数。 */
    39. FuncName = WasmEdge_StringCreateByCString("call_add");
    40. Res = WasmEdge_VMExecute(VMCxt, FuncName, P, 3, R, 1);
    41. WasmEdge_StringDelete(FuncName);
    42. if (WasmEdge_ResultOK(Res)) {
    43.   printf("Run -- `call_add` -- 1234 + 5678 = %d\n",
    44.           WasmEdge_ValueGetI32(R[0]));
    45. } else {
    46.   printf("Run -- `call_add` -- 1234 + 5678 -- failed\n");
    47.   return EXIT_FAILURE;
    48. }

    上面的例子是传递一个函数引用 externref。下面的例子是关于如何在 C++ 中将对象引用作为 externref 传递给 WASM 的。

    1. class AddClass {
    2. public:
    3.   uint32_t add(uint32_t A, uint32_t B) const { return A + B; }
    4. };
    6. AddClass AC;

    然后你可以通过使用 WasmEdge_ValueGenExternRef() API 将对象传入 WasmEdge。

    1. WasmEdge_Value P[3], R[1];
    2. P[0] = WasmEdge_ValueGenExternRef(&AC);
    3. P[1] = WasmEdge_ValueGenI32(1234);
    4. P[2] = WasmEdge_ValueGenI32(5678);
    5. WasmEdge_String FuncName = WasmEdge_StringCreateByCString("call_add");
    6. WasmEdge_Result Res = WasmEdge_VMExecute(VMCxt, FuncName, P, 3, R, 1);
    7. WasmEdge_StringDelete(FuncName);
    8. if (WasmEdge_ResultOK(Res)) {
    9.   std::cout << "Result : " << WasmEdge_ValueGetI32(R[0]) std::endl;
    10.   // 将会打印 `6912`.
    11. } else {
    12.   return EXIT_FAILURE;
    13. }

    在通过引用访问对象的 host 函数中，你可以使用 WasmEdge_ValueGetExternRef() API 来检索对对象的引用。

    1. // 修改上面的教程中的 `ExternAdd`。
    2. WasmEdge_Result ExternAdd(void *, WasmEdge_MemoryInstanceContext *,
    3.                           const WasmEdge_Value *In, WasmEdge_Value *Out) {
    4.   // 函数类型：{externref, i32, i32} -> {i32}
    5.   void *Ptr = WasmEdge_ValueGetExternRef(In[0]);
    6.   AddClass &Obj = *reinterpret_cast<AddClass *>(Ptr);
    7.   uint32_t C =
    8.       Obj.add(WasmEdge_ValueGetI32(In[1]), WasmEdge_ValueGetI32(In[2]));
    9.   Out[0] = WasmEdge_ValueGenI32(C);
    10.   return WasmEdge_Result_Success;
    11. }

    传递一个对象作为仿函数

    与传递类实例一样，需要 functor 对象实例。

    然后你可以通过使用 WasmEdge_ValueGenExternRef() API 将对象传递到 WasmEdge。

    1. WasmEdge_Value P[2], R[1];
    2. P[0] = WasmEdge_ValueGenExternRef(&SS);
    3. P[1] = WasmEdge_ValueGenI32(1024);
    4. WasmEdge_String FuncName = WasmEdge_StringCreateByCString("call_square");
    5. WasmEdge_Result Res = WasmEdge_VMExecute(VMCxt, FuncName, P, 2, R, 1);
    6. WasmEdge_StringDelete(FuncName);
    7. if (WasmEdge_ResultOK(Res)) {
    8.   std::cout << "Result : " << WasmEdge_ValueGetI32(R[0]) std::endl;
    9.   // 将会打印 `1048576`.
    10. } else {
    11.   return EXIT_FAILURE;
    12. }

    在通过引用访问对象的 host 函数中，你可以使用 WasmEdge_ValueGetExternRef API 来检索对该对象的引用，而该引用是一个 functor。

    1. // 修改上文教程中的 `ExternSquare`。
    2. WasmEdge_Result ExternSquare(void *, WasmEdge_MemoryInstanceContext *,
    3.                           const WasmEdge_Value *In, WasmEdge_Value *Out) {
    4.   // 函数类型：{externref, i32, i32} -> {i32}
    5.   void *Ptr = WasmEdge_ValueGetExternRef(In[0]);
    6.   SquareStruct &Obj = *reinterpret_cast<SquareStruct *>(Ptr);
    7.   uint32_t C = Obj(WasmEdge_ValueGetI32(In[1]));
    8.   Out[0] = WasmEdge_ValueGenI32(C);
    9.   return WasmEdge_Result_Success;
    10. }

    传递 STL 对象

    提供了与 host 函数交互的函数可以访问 C++ STL 对象的示例（WAT 是相对应的文本格式）。

    假设 WASM 文件 stl.wasm 被复制到了当前目录。

    以下文的 std::ostream 和 std::string 为例。假设有一个 host 函数可以通过 externref 访问 std::ostream 和 std::string。

    1. // Host 函数，通过 std::ostream 输出 std::string
    2. WasmEdge_Result ExternSTLOStreamStr(void *, WasmEdge_MemoryInstanceContext *,
    3.                                     const WasmEdge_Value *In,
    4.                                     WasmEdge_Value *) {
    5.   // 函数类型：{externref, externref} -> {}
    6.   void *Ptr0 = WasmEdge_ValueGetExternRef(In[0]);
    7.   void *Ptr1 = WasmEdge_ValueGetExternRef(In[1]);
    8.   std::ostream &RefOS = *reinterpret_cast<std::ostream *>(Ptr0);
    9.   std::string &RefStr = *reinterpret_cast<std::string *>(Ptr1);
    10.   RefOS << RefStr;
    11.   return WasmEdge_Result_Success;
    12. }

    假设上面的 host 函数被添加到一个导入对象 ImpObj 中，并且 ImpObj 被注册到一个虚拟机上下文 VMCxt 中。然后你可以通过以下代码实例化 Wasm 模块：

    1. WasmEdge_Result Res = WasmEdge_VMLoadWasmFromFile(VMCxt, "stl.wasm");
    2. if (!WasmEdge_ResultOK(Res)) {
    3.   printf("WASM file loading failed\n");
    4.   return EXIT_FAILURE;
    5. }
    6. Res = WasmEdge_VMValidate(VMCxt);
    7. if (!WasmEdge_ResultOK(Res)) {
    8.   printf("WASM validation failed\n");
    9.   return EXIT_FAILURE;
    10. }
    11. Res = WasmEdge_VMInstantiate(VMCxt);
    12. if (!WasmEdge_ResultOK(Res)) {
    13.   printf("WASM instantiation failed\n");
    14.   return EXIT_FAILURE;
    15. }
    1. std::string PrintStr("Hello world!");
    2. WasmEdge_Value P[2], R[1];
    3. P[0] = WasmEdge_ValueGenExternRef(&std::cout);
    4. P[1] = WasmEdge_ValueGenExternRef(&PrintStr);
    5. WasmEdge_String FuncName = WasmEdge_StringCreateByCString("call_ostream_str");
    6. WasmEdge_Result Res = WasmEdge_VMExecute(VMCxt, FuncName, P, 2, R, 1);
    7. // 将会打印 "Hello world!" 到标准输出 stdout.
    8. WasmEdge_StringDelete(FuncName);
    9. if (!WasmEdge_ResultOK(Res)) {
    10.   return EXIT_FAILURE;
    11. }

    对于其它 C++ STL 对象的情况，例如 std::vector<T>，std::map<T, U> 或 std::set<T>，如果 中的类型是正确的，该对象就可以在 host 函数中被正确访问到。