Upgrade to WasmEdge 0.10.0

Due to the WasmEdge C API breaking changes, this document shows the guideline of programming with WasmEdge C API to upgrade from the 0.9.1 to the 0.10.0 version.

Concepts

  1. Merged the WasmEdge_ImportObjectContext into the WasmEdge_ModuleInstanceContext.

    The WasmEdge_ImportObjectContext which is for the host functions is merged into WasmEdge_ModuleInstanceContext. Developers can use the related APIs to construct host modules.

    • WasmEdge_ImportObjectCreate() is changed to WasmEdge_ModuleInstanceCreate().
    • WasmEdge_ImportObjectDelete() is changed to WasmEdge_ModuleInstanceDelete().
    • WasmEdge_ImportObjectAddFunction() is changed to WasmEdge_ModuleInstanceAddFunction().
    • WasmEdge_ImportObjectAddTable() is changed to WasmEdge_ModuleInstanceAddTable().
    • WasmEdge_ImportObjectAddMemory() is changed to WasmEdge_ModuleInstanceAddMemory().
    • WasmEdge_ImportObjectAddGlobal() is changed to WasmEdge_ModuleInstanceAddGlobal().
    • WasmEdge_ImportObjectCreateWASI() is changed to WasmEdge_ModuleInstanceCreateWASI().
    • WasmEdge_ImportObjectCreateWasmEdgeProcess() is changed to WasmEdge_ModuleInstanceCreateWasmEdgeProcess().
    • WasmEdge_ImportObjectInitWASI() is changed to WasmEdge_ModuleInstanceInitWASI().
    • WasmEdge_ImportObjectInitWasmEdgeProcess() is changed to WasmEdge_ModuleInstanceInitWasmEdgeProcess().

    For the new host function examples, please refer to the example below.

  2. Used the pointer to WasmEdge_FunctionInstanceContext instead of the index in the FuncRef value type.

    For the better performance and security, the FuncRef related APIs used the const WasmEdge_FunctionInstanceContext * for the parameters and returns.

    • WasmEdge_ValueGenFuncRef() is changed to use the const WasmEdge_FunctionInstanceContext * as it’s argument.
    • WasmEdge_ValueGetFuncRef() is changed to return the const WasmEdge_FunctionInstanceContext *.

  3. Supported multiple anonymous WASM module instantiation.

    In the version before 0.9.1, WasmEdge only supports 1 anonymous WASM module to be instantiated at one time. If developers instantiate a new WASM module, the old one will be replaced. After the 0.10.0 version, developers can instantiate multiple anonymous WASM module by Executor and get the Module instance. But for the source code using the VM APIs, the behavior is not changed. For the new examples of instantiating multiple anonymous WASM modules, please refer to the example below.

  4. Behavior changed of WasmEdge_StoreContext.

    The Function, Table, Memory, and Global instances retrievement from the Store is moved to the Module instance. The Store only manage the module linking when instantiation and the named module searching after the 0.10.0 version.

    • WasmEdge_StoreListFunctionLength() and WasmEdge_StoreListFunctionRegisteredLength() is replaced by WasmEdge_ModuleInstanceListFunctionLength().
    • WasmEdge_StoreListTableLength() and WasmEdge_StoreListTableRegisteredLength() is replaced by WasmEdge_ModuleInstanceListTableLength().
    • WasmEdge_StoreListMemoryLength() and WasmEdge_StoreListMemoryRegisteredLength() is replaced by WasmEdge_ModuleInstanceListMemoryLength().
    • WasmEdge_StoreListGlobalLength() and WasmEdge_StoreListGlobalRegisteredLength() is replaced by WasmEdge_ModuleInstanceListGlobalLength().
    • WasmEdge_StoreListFunction() and WasmEdge_StoreListFunctionRegistered() is replaced by WasmEdge_ModuleInstanceListFunction().
    • WasmEdge_StoreListTable() and WasmEdge_StoreListTableRegistered() is replaced by WasmEdge_ModuleInstanceListTable().
    • WasmEdge_StoreListMemory() and WasmEdge_StoreListMemoryRegistered() is replaced by WasmEdge_ModuleInstanceListMemory().
    • WasmEdge_StoreListGlobal() and WasmEdge_StoreListGlobalRegistered() is replaced by WasmEdge_ModuleInstanceListGlobal().
    • WasmEdge_StoreFindFunction() and WasmEdge_StoreFindFunctionRegistered() is replaced by WasmEdge_ModuleInstanceFindFunction().
    • WasmEdge_StoreFindTable() and WasmEdge_StoreFindTableRegistered() is replaced by WasmEdge_ModuleInstanceFindTable().
    • WasmEdge_StoreFindMemory() and WasmEdge_StoreFindMemoryRegistered() is replaced by WasmEdge_ModuleInstanceFindMemory().
    • WasmEdge_StoreFindGlobal() and WasmEdge_StoreFindGlobalRegistered() is replaced by WasmEdge_ModuleInstanceFindGlobal().

    For the new examples of retrieving instances, please refer to the example below.

  5. The WasmEdge_ModuleInstanceContext-based resource management.

    Except the creation of Module instance for the host functons, the Executor will output a Module instance after instantiation. No matter the anonymous or named modules, developers have the responsibility to destroy them by WasmEdge_ModuleInstanceDelete() API. The Store will link to the named Module instance after registering. After the destroyment of a Module instance, the Store will unlink to that automatically; after the destroyment of the Store, the all Module instances the Store linked to will unlink to that Store automatically.

WasmEdge VM changes

The VM APIs are basically not changed, except the ImportObject related APIs.

The following is the example of WASI initialization in WasmEdge 0.9.1 C API:

  1. WasmEdge_ConfigureContext *ConfCxt = WasmEdge_ConfigureCreate();
  2. WasmEdge_ConfigureAddHostRegistration(ConfCxt, WasmEdge_HostRegistration_Wasi);
  3. WasmEdge_VMContext *VMCxt = WasmEdge_VMCreate(ConfCxt, NULL);
  4. /* The following API can retrieve the pre-registration import objects from the VM context. */
  5. /* This API will return `NULL` if the corresponding pre-registration is not set into the configuration. */
  6. WasmEdge_ImportObjectContext *WasiObject =
  7.     WasmEdge_VMGetImportModuleContext(VMCxt, WasmEdge_HostRegistration_Wasi);
  8. /* Initialize the WASI. */
  9. WasmEdge_ImportObjectInitWASI(WasiObject, /* ... ignored */ );
  11. /* ... */
  13. WasmEdge_VMDelete(VMCxt);
  14. WasmEdge_ConfigureDelete(ConfCxt);

Developers can change to use the WasmEdge 0.10.0 C API as follows, with only replacing the WasmEdge_ImportObjectContext into WasmEdge_ModuleInstanceContext:

  1. WasmEdge_ConfigureContext *ConfCxt = WasmEdge_ConfigureCreate();
  2. WasmEdge_ConfigureAddHostRegistration(ConfCxt, WasmEdge_HostRegistration_Wasi);
  3. WasmEdge_VMContext *VMCxt = WasmEdge_VMCreate(ConfCxt, NULL);
  4. /* The following API can retrieve the pre-registration module instances from the VM context. */
  5. /* This API will return `NULL` if the corresponding pre-registration is not set into the configuration. */
  6. WasmEdge_ModuleInstanceContext *WasiModule =
  7.     WasmEdge_VMGetImportModuleContext(VMCxt, WasmEdge_HostRegistration_Wasi);
  8. /* Initialize the WASI. */
  9. WasmEdge_ModuleInstanceInitWASI(WasiModule, /* ... ignored */ );
  11. /* ... */
  13. WasmEdge_VMDelete(VMCxt);
  14. WasmEdge_ConfigureDelete(ConfCxt);

The VM provides a new API for getting the current instantiated anonymous Module instance. For example, if developer want to get the exported Global instance:

  1. /* Assume that a WASM module is instantiated in `VMCxt`, and exports the "global_i32". */
  2. WasmEdge_StoreContext *StoreCxt = WasmEdge_VMGetStoreContext(VMCxt);
  3. WasmEdge_String GlobName = WasmEdge_StringCreateByCString("global_i32");
  4. WasmEdge_GlobalInstanceContext *GlobCxt = WasmEdge_StoreFindGlobal(StoreCxt, GlobName);
  5. WasmEdge_StringDelete(GlobName);

After the WasmEdge 0.10.0 C API, developers can use the WasmEdge_VMGetActiveModule() to get the module instance:

  1. /* Assume that a WASM module is instantiated in `VMCxt`, and exports the "global_i32". */
  2. const WasmEdge_ModuleInstanceContext *ModCxt = WasmEdge_VMGetActiveModule(VMCxt);
  3. /* The example of retrieving the global instance. */
  4. WasmEdge_String GlobName = WasmEdge_StringCreateByCString("global_i32");
  5. WasmEdge_GlobalInstanceContext *GlobCxt = WasmEdge_ModuleInstanceFindGlobal(ModCxt, GlobName);
  6. WasmEdge_StringDelete(GlobName);

WasmEdge Executor changes

Executor helps to instantiate a WASM module, register a WASM module into Store with module name, register the host modules with host functions, or invoke functions.

  1. WASM module instantiation

    In WasmEdge 0.9.1 version, developers can instantiate a WASM module by the Executor API:

    1. WasmEdge_ASTModuleContext *ASTCxt;
    2. /*
    3.  * Assume that `ASTCxt` is a loaded WASM from file or buffer and has passed the validation.
    4.  * Assume that `ExecCxt` is a `WasmEdge_ExecutorContext`.
    5.  * Assume that `StoreCxt` is a `WasmEdge_StoreContext`.
    6.  */
    7. WasmEdge_Result Res = WasmEdge_ExecutorInstantiate(ExecCxt, StoreCxt, ASTCxt);
    8. if (!WasmEdge_ResultOK(Res)) {
    9.   printf("Instantiation phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
    10. }

    Then the WASM module is instantiated into an anonymous module instance and handled by the Store. If a new WASM module is instantiated by this API, the old instantiated module instance will be cleaned. After the WasmEdge 0.10.0 version, the instantiated anonymous module will be outputed and handled by caller, and not only 1 anonymous module instance can be instantiated. Developers have the responsibility to destroy the outputed module instances.

    1. WasmEdge_ASTModuleContext *ASTCxt1, *ASTCxt2;
    2. /*
    3.  * Assume that `ASTCxt1` and `ASTCxt2` are loaded WASMs from different files or buffers,
    4.  * and have both passed the validation.
    5.  * Assume that `ExecCxt` is a `WasmEdge_ExecutorContext`.
    6.  * Assume that `StoreCxt` is a `WasmEdge_StoreContext`.
    7.  */
    8. WasmEdge_ModuleInstanceContext *ModCxt1 = NULL;
    9. WasmEdge_ModuleInstanceContext *ModCxt2 = NULL;
    10. WasmEdge_Result Res = WasmEdge_ExecutorInstantiate(ExecCxt, &ModCxt1, StoreCxt, ASTCxt1);
    11. if (!WasmEdge_ResultOK(Res)) {
    12.   printf("Instantiation phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
    13. }
    14. Res = WasmEdge_ExecutorInstantiate(ExecCxt, &ModCxt2, StoreCxt, ASTCxt2);
    15. if (!WasmEdge_ResultOK(Res)) {
    16.   printf("Instantiation phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
    17. }

  2. WASM module registration with module name

    When instantiating and registering a WASM module with module name, developers can use the WasmEdge_ExecutorRegisterModule() API before WasmEdge 0.9.1.

    1. WasmEdge_ASTModuleContext *ASTCxt;
    2. /*
    3.  * Assume that `ASTCxt` is a loaded WASM from file or buffer and has passed the validation.
    4.  * Assume that `ExecCxt` is a `WasmEdge_ExecutorContext`.
    5.  * Assume that `StoreCxt` is a `WasmEdge_StoreContext`.
    6.  */
    8. /* Register the WASM module into store with the export module name "mod". */
    9. WasmEdge_String ModName = WasmEdge_StringCreateByCString("mod");
    10. Res = WasmEdge_ExecutorRegisterModule(ExecCxt, StoreCxt, ASTCxt, ModName);
    11. WasmEdge_StringDelete(ModName);
    12. if (!WasmEdge_ResultOK(Res)) {
    13.   printf("WASM registration failed: %s\n", WasmEdge_ResultGetMessage(Res));
    14. }

    The same feature is implemented in WasmEdge 0.10.0, but in different API WasmEdge_ExecutorRegister():

    1. WasmEdge_ASTModuleContext *ASTCxt;
    2. /*
    3.  * Assume that `ASTCxt` is a loaded WASM from file or buffer and has passed the validation.
    4.  * Assume that `ExecCxt` is a `WasmEdge_ExecutorContext`.
    5.  * Assume that `StoreCxt` is a `WasmEdge_StoreContext`.
    6.  */
    8. /* Register the WASM module into store with the export module name "mod". */
    9. WasmEdge_String ModName = WasmEdge_StringCreateByCString("mod");
    10. /* The output module instance. */
    11. WasmEdge_ModuleInstanceContext *ModCxt = NULL;
    12. Res = WasmEdge_ExecutorRegister(ExecCxt, &ModCxt, StoreCxt, ASTCxt, ModName);
    13. WasmEdge_StringDelete(ModName);
    14. if (!WasmEdge_ResultOK(Res)) {
    15.   printf("WASM registration failed: %s\n", WasmEdge_ResultGetMessage(Res));
    16. }

    Developers have the responsibility to destroy the outputed module instances.

  3. Host module registration

    In WasmEdge 0.9.1, developers can create a WasmEdge_ImportObjectContext and register into Store.

    1. /* Create the import object with the export module name. */
    2. WasmEdge_String ModName = WasmEdge_StringCreateByCString("module");
    3. WasmEdge_ImportObjectContext *ImpObj = WasmEdge_ImportObjectCreate(ModName);
    4. WasmEdge_StringDelete(ModName);
    5. /*
    6.  * ...
    7.  * Add the host functions, tables, memories, and globals into the import object.
    8.  */
    9. /* The import module context has already contained the export module name. */
    10. Res = WasmEdge_ExecutorRegisterImport(ExecCxt, StoreCxt, ImpObj);
    11. if (!WasmEdge_ResultOK(Res)) {
    12.   printf("Import object registration failed: %s\n", WasmEdge_ResultGetMessage(Res));
    13. }

    After WasmEdge 0.10.0, developers should use the WasmEdge_ModuleInstanceContext instead:

    1. /* Create the module instance with the export module name. */
    2. WasmEdge_String ModName = WasmEdge_StringCreateByCString("module");
    3. WasmEdge_ModuleInstanceContext *ModCxt = WasmEdge_ModuleInstanceCreate(ModName);
    4. WasmEdge_StringDelete(ModName);
    5. /*
    6.  * ...
    7.  * Add the host functions, tables, memories, and globals into the module instance.
    8.  */
    9. /* The module instance context has already contained the export module name. */
    10. Res = WasmEdge_ExecutorRegisterImport(ExecCxt, StoreCxt, ModCxt);
    11. if (!WasmEdge_ResultOK(Res)) {
    12.   printf("Module instance registration failed: %s\n", WasmEdge_ResultGetMessage(Res));
    13. }

    Developers have the responsibility to destroy the created module instances.

  4. WASM function invokation

    This example uses the fibonacci.wasm, and the corresponding WAT file is at fibonacci.wat. In WasmEdge 0.9.1 version, developers can invoke a WASM function with the export function name:

    1. /* Create the store context. The store context holds the instances. */
    2. WasmEdge_StoreContext *StoreCxt = WasmEdge_StoreCreate();
    3. /* Result. */
    4. WasmEdge_Result Res;
    6. /* Create the loader context. The configure context can be NULL. */
    7. WasmEdge_LoaderContext *LoadCxt = WasmEdge_LoaderCreate(NULL);
    8. /* Create the validator context. The configure context can be NULL. */
    9. WasmEdge_ValidatorContext *ValidCxt = WasmEdge_ValidatorCreate(NULL);
    10. /* Create the executor context. The configure context and the statistics context can be NULL. */
    11. WasmEdge_ExecutorContext *ExecCxt = WasmEdge_ExecutorCreate(NULL, NULL);
    13. /* Load the WASM file or the compiled-WASM file and convert into the AST module context. */
    14. WasmEdge_ASTModuleContext *ASTCxt = NULL;
    15. Res = WasmEdge_LoaderParseFromFile(LoadCxt, &ASTCxt, "fibonacci.wasm");
    16. if (!WasmEdge_ResultOK(Res)) {
    17.   printf("Loading phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
    18.   return -1;
    19. }
    20. /* Validate the WASM module. */
    21. Res = WasmEdge_ValidatorValidate(ValidCxt, ASTCxt);
    22. if (!WasmEdge_ResultOK(Res)) {
    23.   printf("Validation phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
    24.   return -1;
    25. }
    26. /* Instantiate the WASM module into the store context. */
    27. Res = WasmEdge_ExecutorInstantiate(ExecCxt, StoreCxt, ASTCxt);
    28. if (!WasmEdge_ResultOK(Res)) {
    29.   printf("Instantiation phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
    30.   return -1;
    31. }
    32. /* Invoke the function which is exported with the function name "fib". */
    33. WasmEdge_String FuncName = WasmEdge_StringCreateByCString("fib");
    34. WasmEdge_Value Params[1] = { WasmEdge_ValueGenI32(18) };
    35. WasmEdge_Value Returns[1];
    36. Res = WasmEdge_ExecutorInvoke(ExecCxt, StoreCxt, FuncName, Params, 1, Returns, 1);
    37. if (WasmEdge_ResultOK(Res)) {
    38.   printf("Get the result: %d\n", WasmEdge_ValueGetI32(Returns[0]));
    39. } else {
    40.   printf("Execution phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
    41.   return -1;
    42. }
    44. WasmEdge_ASTModuleDelete(ASTCxt);
    45. WasmEdge_LoaderDelete(LoadCxt);
    46. WasmEdge_ValidatorDelete(ValidCxt);
    47. WasmEdge_ExecutorDelete(ExecCxt);
    48. WasmEdge_StoreDelete(StoreCxt);

    After the WasmEdge 0.10.0, developers should retrieve the Function instance by function name first.

    1. /*
    2.  * ...
    3.  * Ignore the unchanged steps before validation. Please refer to the sample code above.
    4.  */
    5. WasmEdge_ModuleInstanceContext *ModCxt = NULL;
    6. /* Instantiate the WASM module. */
    7. Res = WasmEdge_ExecutorInstantiate(ExecCxt, &ModCxt1, StoreCxt, ASTCxt);
    8. if (!WasmEdge_ResultOK(Res)) {
    9.   printf("Instantiation phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
    10.   return -1;
    11. }
    12. /* Retrieve the function instance by name. */
    13. WasmEdge_String FuncName = WasmEdge_StringCreateByCString("fib");
    14. WasmEdge_FunctionInstanceContext *FuncCxt = WasmEdge_ModuleInstanceFindFunction(ModCxt, FuncName);
    15. WasmEdge_StringDelete(FuncName);
    16. /* Invoke the function. */
    17. WasmEdge_Value Params[1] = { WasmEdge_ValueGenI32(18) };
    18. WasmEdge_Value Returns[1];
    19. Res = WasmEdge_ExecutorInvoke(ExecCxt, FuncCxt, Params, 1, Returns, 1);
    20. if (WasmEdge_ResultOK(Res)) {
    21.   printf("Get the result: %d\n", WasmEdge_ValueGetI32(Returns[0]));
    22. } else {
    23.   printf("Execution phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
    24.   return -1;
    25. }
    27. WasmEdge_ModuleInstanceDelete(ModCxt);
    28. WasmEdge_ASTModuleDelete(ASTCxt);
    29. WasmEdge_LoaderDelete(LoadCxt);
    30. WasmEdge_ValidatorDelete(ValidCxt);
    31. WasmEdge_ExecutorDelete(ExecCxt);
    32. WasmEdge_StoreDelete(StoreCxt);

Instances retrievement

This example uses the fibonacci.wasm, and the corresponding WAT file is at fibonacci.wat.

Before the WasmEdge 0.9.1 versions, developers can retrieve all exported instances of named or anonymous modules from Store:

  1. /* Create the store context. The store context holds the instances. */
  2. WasmEdge_StoreContext *StoreCxt = WasmEdge_StoreCreate();
  3. /* Result. */
  4. WasmEdge_Result Res;
  6. /* Create the loader context. The configure context can be NULL. */
  7. WasmEdge_LoaderContext *LoadCxt = WasmEdge_LoaderCreate(NULL);
  8. /* Create the validator context. The configure context can be NULL. */
  9. WasmEdge_ValidatorContext *ValidCxt = WasmEdge_ValidatorCreate(NULL);
  10. /* Create the executor context. The configure context and the statistics context can be NULL. */
  11. WasmEdge_ExecutorContext *ExecCxt = WasmEdge_ExecutorCreate(NULL, NULL);
  13. /* Load the WASM file or the compiled-WASM file and convert into the AST module context. */
  14. WasmEdge_ASTModuleContext *ASTCxt = NULL;
  15. Res = WasmEdge_LoaderParseFromFile(LoadCxt, &ASTCxt, "fibonacci.wasm");
  16. if (!WasmEdge_ResultOK(Res)) {
  17.   printf("Loading phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
  18.   return -1;
  19. }
  20. /* Validate the WASM module. */
  21. Res = WasmEdge_ValidatorValidate(ValidCxt, ASTCxt);
  22. if (!WasmEdge_ResultOK(Res)) {
  23.   printf("Validation phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
  24.   return -1;
  25. }
  26. /* Example: register and instantiate the WASM module with the module name "module_fib". */
  27. WasmEdge_String ModName = WasmEdge_StringCreateByCString("module_fib");
  28. Res = WasmEdge_ExecutorRegisterModule(ExecCxt, StoreCxt, ASTCxt, ModName);
  29. if (!WasmEdge_ResultOK(Res)) {
  30.   printf("Instantiation phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
  31.   return -1;
  32. }
  33. /* Example: Instantiate the WASM module into the store context. */
  34. Res = WasmEdge_ExecutorInstantiate(ExecCxt, StoreCxt, ASTCxt);
  35. if (!WasmEdge_ResultOK(Res)) {
  36.   printf("Instantiation phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
  37.   return -1;
  38. }
  39. WasmEdge_StringDelete(ModName);
  41. /* Now, developers can retrieve the exported instances from the store. */
  42. /* Take the exported functions as example. This WASM exports the function "fib". */
  43. WasmEdge_String FuncName = WasmEdge_StringCreateByCString("fib");
  44. WasmEdge_FunctionInstanceContext *FoundFuncCxt;
  45. /* Find the function "fib" from the instantiated anonymous module. */
  46. FoundFuncCxt = WasmEdge_StoreFindFunction(StoreCxt, FuncName);
  47. /* Find the function "fib" from the registered module "module_fib". */
  48. ModName = WasmEdge_StringCreateByCString("module_fib");
  49. FoundFuncCxt = WasmEdge_StoreFindFunctionRegistered(StoreCxt, ModName, FuncName);
  50. WasmEdge_StringDelete(ModName);
  51. WasmEdge_StringDelete(FuncName);
  53. WasmEdge_ASTModuleDelete(ASTCxt);
  54. WasmEdge_LoaderDelete(LoadCxt);
  55. WasmEdge_ValidatorDelete(ValidCxt);
  56. WasmEdge_ExecutorDelete(ExecCxt);
  57. WasmEdge_StoreDelete(StoreCxt);

After the WasmEdge 0.10.0, developers can instantiate several anonymous Module instances, and should retrieve the exported instances from named or anonymous Module instances:

  1. /* Create the store context. The store context is the object to link the modules for imports and exports. */
  2. WasmEdge_StoreContext *StoreCxt = WasmEdge_StoreCreate();
  3. /* Result. */
  4. WasmEdge_Result Res;
  6. /* Create the loader context. The configure context can be NULL. */
  7. WasmEdge_LoaderContext *LoadCxt = WasmEdge_LoaderCreate(NULL);
  8. /* Create the validator context. The configure context can be NULL. */
  9. WasmEdge_ValidatorContext *ValidCxt = WasmEdge_ValidatorCreate(NULL);
  10. /* Create the executor context. The configure context and the statistics context can be NULL. */
  11. WasmEdge_ExecutorContext *ExecCxt = WasmEdge_ExecutorCreate(NULL, NULL);
  13. /* Load the WASM file or the compiled-WASM file and convert into the AST module context. */
  14. WasmEdge_ASTModuleContext *ASTCxt = NULL;
  15. Res = WasmEdge_LoaderParseFromFile(LoadCxt, &ASTCxt, "fibonacci.wasm");
  16. if (!WasmEdge_ResultOK(Res)) {
  17.   printf("Loading phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
  18.   return -1;
  19. }
  20. /* Validate the WASM module. */
  21. Res = WasmEdge_ValidatorValidate(ValidCxt, ASTCxt);
  22. if (!WasmEdge_ResultOK(Res)) {
  23.   printf("Validation phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
  24.   return -1;
  25. }
  26. /* Example: register and instantiate the WASM module with the module name "module_fib". */
  27. WasmEdge_ModuleInstanceContext *NamedModCxt = NULL;
  28. WasmEdge_String ModName = WasmEdge_StringCreateByCString("module_fib");
  29. Res = WasmEdge_ExecutorRegister(ExecCxt, &NamedModCxt, StoreCxt, ASTCxt, ModName);
  30. if (!WasmEdge_ResultOK(Res)) {
  31.   printf("Instantiation phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
  32.   return -1;
  33. }
  34. /* Example: Instantiate the WASM module and get the output module instance. */
  35. WasmEdge_ModuleInstanceContext *ModCxt = NULL;
  36. Res = WasmEdge_ExecutorInstantiate(ExecCxt, &ModCxt, StoreCxt, ASTCxt);
  37. if (!WasmEdge_ResultOK(Res)) {
  38.   printf("Instantiation phase failed: %s\n", WasmEdge_ResultGetMessage(Res));
  39.   return -1;
  40. }
  41. WasmEdge_StringDelete(ModName);
  43. /* Now, developers can retrieve the exported instances from the module instaces. */
  44. /* Take the exported functions as example. This WASM exports the function "fib". */
  45. WasmEdge_String FuncName = WasmEdge_StringCreateByCString("fib");
  46. WasmEdge_FunctionInstanceContext *FoundFuncCxt;
  47. /* Find the function "fib" from the instantiated anonymous module. */
  48. FoundFuncCxt = WasmEdge_ModuleInstanceFindFunction(ModCxt, FuncName);
  49. /* Find the function "fib" from the registered module "module_fib". */
  50. FoundFuncCxt = WasmEdge_ModuleInstanceFindFunction(NamedModCxt, FuncName);
  51. /* Or developers can get the named module instance from the store: */
  52. ModName = WasmEdge_StringCreateByCString("module_fib");
  53. const WasmEdge_ModuleInstanceContext *ModCxtGot = WasmEdge_StoreFindModule(StoreCxt, ModName);
  54. WasmEdge_StringDelete(ModName);
  55. FoundFuncCxt = WasmEdge_ModuleInstanceFindFunction(ModCxtGot, FuncName);
  56. WasmEdge_StringDelete(FuncName);
  58. WasmEdge_ModuleInstanceDelete(NamedModCxt);
  59. WasmEdge_ModuleInstanceDelete(ModCxt);
  60. WasmEdge_ASTModuleDelete(ASTCxt);
  61. WasmEdge_LoaderDelete(LoadCxt);
  62. WasmEdge_ValidatorDelete(ValidCxt);
  63. WasmEdge_ExecutorDelete(ExecCxt);
  64. WasmEdge_StoreDelete(StoreCxt);

Host functions

The difference of host functions are the replacement of WasmEdge_ImportObjectContext.

  1. /* Host function body definition. */
  2. WasmEdge_Result Add(void *Data, WasmEdge_MemoryInstanceContext *MemCxt,
  3.                     const WasmEdge_Value *In, WasmEdge_Value *Out) {
  4.   int32_t Val1 = WasmEdge_ValueGetI32(In[0]);
  5.   int32_t Val2 = WasmEdge_ValueGetI32(In[1]);
  6.   Out[0] = WasmEdge_ValueGenI32(Val1 + Val2);
  7.   return WasmEdge_Result_Success;
  8. }
  10. /* Create the import object. */
  11. WasmEdge_String ExportName = WasmEdge_StringCreateByCString("module");
  12. WasmEdge_ImportObjectContext *ImpObj = WasmEdge_ImportObjectCreate(ExportName);
  13. WasmEdge_StringDelete(ExportName);
  15. /* Create and add a function instance into the import object. */
  16. enum WasmEdge_ValType ParamList[2] = { WasmEdge_ValType_I32, WasmEdge_ValType_I32 };
  17. enum WasmEdge_ValType ReturnList[1] = { WasmEdge_ValType_I32 };
  18. WasmEdge_FunctionTypeContext *HostFType = 
  19.     WasmEdge_FunctionTypeCreate(ParamList, 2, ReturnList, 1);
  20. WasmEdge_FunctionInstanceContext *HostFunc =
  21.     WasmEdge_FunctionInstanceCreate(HostFType, Add, NULL, 0);
  22. /*
  23.  * The third parameter is the pointer to the additional data object.
  24.  * Developers should guarantee the life cycle of the data, and it can be
  25.  * `NULL` if the external data is not needed.
  26.  */
  27. WasmEdge_FunctionTypeDelete(HostFType);
  28. WasmEdge_String FuncName = WasmEdge_StringCreateByCString("add");
  29. WasmEdge_ImportObjectAddFunction(ImpObj, FuncName, HostFunc);
  30. WasmEdge_StringDelete(FuncName);
  32. /*
  33.  * The import objects should be deleted.
  34.  * Developers should __NOT__ destroy the instances added into the import object contexts.
  35.  */
  36. WasmEdge_ImportObjectDelete(ImpObj);

Developers can use the WasmEdge_ModuleInstanceContext to upgrade to WasmEdge 0.10.0 easily.

  1. /* Host function body definition. */
  2. WasmEdge_Result Add(void *Data, WasmEdge_MemoryInstanceContext *MemCxt,
  3.                     const WasmEdge_Value *In, WasmEdge_Value *Out) {
  4.   int32_t Val1 = WasmEdge_ValueGetI32(In[0]);
  5.   int32_t Val2 = WasmEdge_ValueGetI32(In[1]);
  6.   Out[0] = WasmEdge_ValueGenI32(Val1 + Val2);
  7.   return WasmEdge_Result_Success;
  8. }
  10. /* Create a module instance. */
  11. WasmEdge_String ExportName = WasmEdge_StringCreateByCString("module");
  12. WasmEdge_ModuleInstanceContext *HostModCxt = WasmEdge_ModuleInstanceCreate(ExportName);
  13. WasmEdge_StringDelete(ExportName);
  15. /* Create and add a function instance into the module instance. */
  16. enum WasmEdge_ValType ParamList[2] = { WasmEdge_ValType_I32, WasmEdge_ValType_I32 };
  17. enum WasmEdge_ValType ReturnList[1] = { WasmEdge_ValType_I32 };
  18. WasmEdge_FunctionTypeContext *HostFType = 
  19.     WasmEdge_FunctionTypeCreate(ParamList, 2, ReturnList, 1);
  20. WasmEdge_FunctionInstanceContext *HostFunc =
  21.     WasmEdge_FunctionInstanceCreate(HostFType, Add, NULL, 0);
  22. /*
  23.  * The third parameter is the pointer to the additional data object.
  24.  * Developers should guarantee the life cycle of the data, and it can be
  25.  * `NULL` if the external data is not needed.
  26.  */
  27. WasmEdge_FunctionTypeDelete(HostFType);
  28. WasmEdge_String FuncName = WasmEdge_StringCreateByCString("add");
  29. WasmEdge_ModuleInstanceAddFunction(HostModCxt, FuncName, HostFunc);
  30. WasmEdge_StringDelete(FuncName);
  32. /*
  33.  * The module instance should be deleted.
  34.  * Developers should __NOT__ destroy the instances added into the module instance contexts.
  35.  */
  36. WasmEdge_ModuleInstanceDelete(HostModCxt);