Upgrade to WasmEdge-Go v0.12.0
Due to the WasmEdge-Go API breaking changes, this document shows the guideline of programming with WasmEdge-Go API to upgrade from the v0.11.2
to the v0.12.0
version.
Concepts
-
Removed the members of the
wasmedge.HostRegistration
related const values.The following const values are removed:
wasmedge.WasmEdge_Process
wasmedge.WasiNN
wasmedge.WasiCrypto_Common
wasmedge.WasiCrypto_AsymmetricCommon
wasmedge.WasiCrypto_Kx
wasmedge.WasiCrypto_Signatures
wasmedge.WasiCrypto_Symmetric
The
wasmedge.VM
objects will create and register the host modules automatically now. If the plug-ins are not loaded, theVM
objects will create and register the mock modules to prevent from import failed. -
Removed the module instance creation functions of the plug-ins.
The following APIs are removed:
wasmedge.NewWasiNNModule()
wasmedge.NewWasiCryptoCommonModule()
wasmedge.NewWasiCryptoAsymmetricCommonModule()
wasmedge.NewWasiCryptoKxModule()
wasmedge.NewWasiCryptoSignaturesModule()
wasmedge.NewWasiCryptoSymmetricModule()
wasmedge.NewWasmEdgeProcessModule()
For the new examples for creating the module instances from plug-ins, please refer to the example below.
-
New module instance retrieving API of
VM
objects.- Added
(*wasmedge.VM).GetRegisteredModule()
for retrieving registered named module inVM
objects quickly. - Added
(*wasmedge.VM).ListRegisteredModule()
for listing registered named modules inVM
objects quickly.
- Added
The wasmedge.HostRegistration
const values for plug-ins are not necessary in VM objects
Before the version v0.11.2
, developers should add the configurations when they want to load the plug-ins in VM:
// Assume that wasi_crypto plug-in is installed in the default plug-in path.
wasmedge.LoadPluginDefaultPaths()
conf := wasmedge.NewConfigure(wasmedge.WASI)
comf.AddConfig(wasmedge.WasiCrypto_Common)
comf.AddConfig(wasmedge.WasiCrypto_AsymmetricCommon)
comf.AddConfig(wasmedge.WasiCrypto_Kx)
comf.AddConfig(wasmedge.WasiCrypto_Signatures)
comf.AddConfig(wasmedge.WasiCrypto_Symmetric)
vm := wasmedge.NewVMWithConfig(conf)
conf.Release()
store := vm.GetStore()
modulelist := store.ListModule()
for _, name := range modulelist {
fmt.Println(name)
}
// Will print:
// wasi_ephemeral_crypto_asymmetric_common
// wasi_ephemeral_crypto_common
// wasi_ephemeral_crypto_kx
// wasi_ephemeral_crypto_signatures
// wasi_ephemeral_crypto_symmetric
vm.Release()
After v0.12.0
, the plug-ins will automatically loaded after the wasmedge.LoadPluginDefaultPaths()
called or the specific path given into the wasmedge.LoadPluginFromPath()
API.
For the plug-ins not installed, the mocked modules will be registered into VM
objects and will print the error message when invoking the host functions to notice the users to install the plug-in.
wasmedge.LoadPluginDefaultPaths()
// The `wasmedge.WASI` is still needed.
conf := wasmedge.NewConfigure(wasmedge.WASI)
vm := wasmedge.NewVMWithConfig(conf)
conf.Release()
modulelist := vm.ListRegisteredModule()
for _, name := range modulelist {
fmt.Println(name)
}
// Will print:
// wasi_ephemeral_crypto_asymmetric_common
// wasi_ephemeral_crypto_common
// wasi_ephemeral_crypto_kx
// wasi_ephemeral_crypto_signatures
// wasi_ephemeral_crypto_symmetric
// wasi_ephemeral_nn
// wasi_snapshot_preview1
// wasmedge_httpsreq
// wasmedge_process
vm.Release()
Note: The
wasmedge.WASI
configuration is still needed if developers want to use the WASI.
Creating the module instance from a plug-in
When developers didn't use the VM objects to load the plug-ins, they can use the creation functions before the v0.11.2
versions:
// Assume that wasi_crypto plug-in is installed in the default plug-in path.
wasmedge.LoadPluginDefaultPaths()
cryptocommonmod := wasmedge.NewWasiCryptoCommonModule()
cryptocommonmod.Release()
But it not make sense and not extensionable if developers should use different APIs for the different plug-ins.
After the v0.12.0
version, the wasmedge.Plugin
struct is added, and developers can use the general API to create the module instances:
// Assume that wasi_crypto plug-in is installed in the default plug-in path.
wasmedge.LoadPluginDefaultPaths()
cryptoplugin := wasmedge.FindPlugin("wasi_crypto")
if ctyptoplugin == nil {
fmt.Println("FAIL: Cannot find the wasi_crypto plugin.")
return
}
cryptocommonmod := cryptoplugin.CreateModule("wasi_crypto_common")
cryptocommonmod.Release()
Retrieving the module instances from the VM context
Before the version v0.11.2
, developers can retrieve the WASI
or the modules from plug-ins with the wasmedge.HostRegistration
const values, or retrieve the registered modules from the store
object.
// Assume that wasi_crypto plug-in is installed in the default plug-in path.
wasmedge.LoadPluginDefaultPaths()
conf := wasmedge.NewConfigure(wasmedge.WASI)
comf.AddConfig(wasmedge.WasiCrypto_Common)
comf.AddConfig(wasmedge.WasiCrypto_AsymmetricCommon)
comf.AddConfig(wasmedge.WasiCrypto_Kx)
comf.AddConfig(wasmedge.WasiCrypto_Signatures)
comf.AddConfig(wasmedge.WasiCrypto_Symmetric)
vm := wasmedge.NewVMWithConfig(conf)
conf.Release()
// Get the WASI module instance.
wasimod := vm.GetImportModule(wasmedge.WASI)
// Get the WASI-crypto-common module instance.
cryptocommonmod := vm.GetImportModule(wasmedge.WasiCrypto_Common)
// Get the registered module instance by name.
store := vm.GetStore()
cryptokxmod := store.FindModule("wasi_ephemeral_crypto_kx")
vm.Release()
After the v0.12.0
version, due to removing the plug-in related configurations and automatically registering the plug-ins into VM objects, developers cannot use the (*wasmedge.VM).GetImportModule()
API to retrieve the module instances except the built-in host modules (WASI
currently).
However, developers can use the new APIs to retrieve the registered module instances more quickly.
// Assume that wasi_crypto plug-in is installed in the default plug-in path.
wasmedge.LoadPluginDefaultPaths()
// Add the WASI configurations.
conf := wasmedge.NewConfigure(wasmedge.WASI)
vm := wasmedge.NewVMWithConfig(conf)
conf.Release()
// Get the WASI module instance.
wasimod := vm.GetImportModule(wasmedge.WASI)
// Get the registered WASI-crypto-common module instance by name.
cryptocommonmod := vm.GetRegisteredModule("wasi_ephemeral_crypto_common")
vm.Release()