Crate wasmedge_sdk

Expand description

Overview

The wasmedge-sdk crate defines a group of high-level Rust APIs, which are used to build up business applications.

Notice that wasmedge-sdk requires Rust v1.66 or above in the stable channel.

Build

To use or build the wasmedge-sdk crate, the WasmEdge library is required. Please refer to WasmEdge Installation and Uninstallation to install the WasmEdge library.

The following table provides the versioning information about each crate of WasmEdge Rust bindings.

wasmedge-sdk	WasmEdge lib	wasmedge-sys	wasmedge-types	wasmedge-macro
0.8.1	0.12.1	0.13.1	0.4.1	0.3.0
0.8.0	0.12.0	0.13.0	0.4.1	0.3.0
0.7.1	0.11.2	0.12.2	0.3.1	0.3.0
0.7.0	0.11.2	0.12	0.3.1	0.3.0
0.6.0	0.11.2	0.11	0.3.0	0.2.0
0.5.0	0.11.1	0.10	0.3.0	0.1.0
0.4.0	0.11.0	0.9	0.2.1	-
0.3.0	0.10.1	0.8	0.2	-
0.1.0	0.10.0	0.7	0.1	-

Example

The example below is using wasmedge-sdk to run a WebAssembly module written with its WAT format (textual format). If you would like more examples, please refer to Examples of WasmEdge RustSDK.

use wasmedge_sdk::{
    error::HostFuncError, host_function, params, wat2wasm, Caller, ImportObjectBuilder, Module,
    VmBuilder, WasmValue,
};
 
// We define a function to act as our "env" "say_hello" function imported in the
// Wasm program above.
#[host_function]
pub fn say_hello(_caller: Caller, _args: Vec<WasmValue>) -> Result<Vec<WasmValue>, HostFuncError> {
    println!("Hello, world!");
 
    Ok(vec![])
}
 
#[cfg_attr(test, test)]
fn main() -> anyhow::Result<()> {
    // create an import module
    let import = ImportObjectBuilder::new()
        .with_func::<(), ()>("say_hello", say_hello)?
        .build("env")?;
 
    let wasm_bytes = wat2wasm(
        br#"
    (module
      ;; First we define a type with no parameters and no results.
      (type $no_args_no_rets_t (func (param) (result)))
     
      ;; Then we declare that we want to import a function named "env" "say_hello" with
      ;; that type signature.
      (import "env" "say_hello" (func $say_hello (type $no_args_no_rets_t)))
     
      ;; Finally we create an entrypoint that calls our imported function.
      (func $run (type $no_args_no_rets_t)
        (call $say_hello))
      ;; And mark it as an exported function named "run".
      (export "run" (func $run)))
    "#,
    )?;
 
    // loads a wasm module from the given in-memory bytes
    let module = Module::from_bytes(None, wasm_bytes)?;
 
    // create an executor
    VmBuilder::new()
        .build()?
        .register_import_module(import)?
        .register_module(Some("extern"), module)?
        .run_func(Some("extern"), "run", params!())?;
 
    Ok(())
}

Modules

config

Defines the structs used to construct configurations.

dock

Defines WasmEdge VmDock and Param types.

error

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines WasmEdge error types.

plugin

Defines plugin related structs.

types

Defines the general types.

wasi

Defines wasi module instance types, including WasiInstance, WasiNnInstance, wasi-crypto instances.

Macros

params

Used to pass arguments to the following methods:

Structs

Caller

Represents the calling frame on top of stack.

Compiler

Defines WasmEdge ahead-of-time(AOT) compiler and the relevant APIs.

CoreVersion

The version info of WasmEdge core

Driver

Defines WasmEdge Driver functions

Executor

Defines an execution environment for both pure WASM and compiled WASM.

ExportType

Defines the types of the exported instances.

Func

Defines a host function instance.

FuncRef

Defines a reference to a host function.

FuncType

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Struct of WasmEdge FuncType.

FuncTypeBuilder

Defines a type builder for creating a FuncType instance.

Global

Defines a WebAssembly global variable, which stores a single value of the given GlobalType and a flag indicating whether it is mutable or not.

GlobalType

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Struct of WasmEdge GlobalType.

ImportObject

Defines an import object that contains the required import data used when instantiating a module.

ImportObjectBuilder

Creates a normal or wasi import object.

ImportType

Defines the types of the imported instances.

Instance

Represents an instantiated module.

LogManager

Manipulates the runtime logger.

Memory

Defines a linear memory.

MemoryType

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Struct of WasmEdge MemoryType.

Module

Defines compiled in-memory representation of an input WASM binary.

Statistics

Used to collect statistics of the WasmEdge runtime, such as the count of instructions in execution.

Store

Represents all global state that can be manipulated by WebAssembly programs. A store consists of the runtime representation of all instances of functions, tables, memories, and globals.

Table

Defines a table storing the references to host functions or external objects.

TableType

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Struct of WasmEdge TableType.

Vm

A Vm defines a virtual environment for managing WebAssembly programs.

VmBuilder

Constructs a Vm instance.

Enums

CompilerOptimizationLevel

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines WasmEdge AOT compiler optimization level.

CompilerOutputFormat

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines WasmEdge AOT compiler output binary format.

ExternalInstanceType

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines the type of external WasmEdge instances.

HostRegistration

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines WasmEdge host module registration enum.

Mutability

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines the mutability property of WasmEdge Global variables.

RefType

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines WasmEdge reference types.

ValType

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Defines WasmEdge value types.

Traits

AsInstance

The object used as an module instance is required to implement this trait.

Engine

The object that is used to perform a host function is required to implement this trait.

WasmVal

Defines the function converting a value of Rust type to the one of Wasm type.

WasmValType

Describes the mapping of Rust type to Wasm type.

WasmValTypeList

Describes the mapping of a tuple of Rust types to Wasm types.

Functions

wat2wasm

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module.

Type Definitions

CallingFrame

WasmEdgeResult

Parses in-memory bytes as either the WebAssembly Text format, or a binary WebAssembly module The WasmEdge result type.

WasmValue

WebAssembly value type.

Attribute Macros

async_host_function

Declare a native async function that will be used to create an async host function instance.

host_function

Declare a native function that will be used to create a host function instance.