wasmedge-hs-0.17.1.0: Haskell bindings for the WasmEdge WebAssembly runtime
Copyright(c) 2026 Tushar Adhatrao
LicenseMIT
Stabilitystable
Safe HaskellNone
LanguageGHC2021

WasmEdge.VM

Description

The VM context provides the highest-level interface for running WASM modules. It bundles a loader, validator, executor, and store internally.

Quick start

import WasmEdge.VM
import WasmEdge.Types

main :: IO ()
main = do
  result withVM Nothing Nothing $ vm - do
    runWasmFile vm "hello.wasm" "main" []
  case result of
    Left err  -> putStrLn $ "Error: " ++ show err
    Right vals -> print vals

Step-by-step pipeline

For more control, use the load → validate → instantiate → execute pipeline:

withVM (Just cfg) Nothing $ vm -> do
  loadWasmFile vm "module.wasm"    >>= throwOnFail
  validate vm                       >>= throwOnFail
  instantiate vm                    >>= throwOnFail
  execute vm "run" [WasmI32 42]    >>= either throwIO pure
Synopsis

VM context

data VM #

Opaque WasmEdge VM context.

Automatically retains registered host ModuleInstances to guarantee their lifetime as long as the VM is alive, preventing use-after-free bugs.

Instances

Instances details
NFData VM # 
Instance details

Defined in WasmEdge.VM

Methods

rnf :: VM -> () #

createVM :: Maybe Configure -> Maybe Store -> IO VM #

Create a VM context.

createVM mCfg mStore uses the optional Configure context mCfg and optional shared Store context mStore. Pass Nothing to use defaults.

deleteVM :: VM -> IO () #

Delete a VM context explicitly.

withVM :: Maybe Configure -> Maybe Store -> (VM -> IO a) -> IO a #

Scoped VM context.

Declarative VM configuration

data VMConfig #

Declarative configuration record for initializing a VM. Inspired by wasmedge-sdk's VmBuilder in Rust.

Constructors

VMConfig 

Fields

defaultVMConfig :: VMConfig #

Default VM configuration with default options and fresh store.

createVMWithConfig :: VMConfig -> IO VM #

Create a VM context using a VMConfig.

withVMConfig :: VMConfig -> (VM -> IO a) -> IO a #

Scoped VM context with declarative VMConfig.

One-shot execution

runWasmFile #

Arguments

:: VM 
-> FilePath

Path to the .wasm or .so file

-> Text

Function name

-> [WasmVal]

Parameters

-> IO (WasmResult [WasmVal]) 

Load, instantiate, and run a WASM file in one call.

runWasmBytes :: VM -> ByteString -> Text -> [WasmVal] -> IO (WasmResult [WasmVal]) #

Load, instantiate, and run a WASM module from a ByteString.

Async one-shot execution

asyncRunWasmFile :: VM -> FilePath -> Text -> [WasmVal] -> IO Async #

Async variant of runWasmFile.

asyncRunWasmBytes :: VM -> ByteString -> Text -> [WasmVal] -> IO Async #

Async variant of runWasmBytes.

Module registration

registerModuleFromFile :: VM -> Text -> FilePath -> IO (WasmResult ()) #

Register and instantiate a named module from a file.

registerModuleFromBytes :: VM -> Text -> ByteString -> IO (WasmResult ()) #

Register and instantiate a named module from bytes.

registerModuleFromImport :: VM -> ModuleInstance -> IO (WasmResult ()) #

Register an existing ModuleInstance into the VM. The VM automatically retains the module to guarantee its lifetime.

registerModuleFromImportWithAlias :: VM -> Text -> ModuleInstance -> IO (WasmResult ()) #

Register an existing ModuleInstance into the VM under a custom alias name. The VM automatically retains the module to guarantee its lifetime.

Step-by-step pipeline

loadWasmFile :: VM -> FilePath -> IO (WasmResult ()) #

Load a WASM file into the VM (does not validate or instantiate).

loadWasmBytes :: VM -> ByteString -> IO (WasmResult ()) #

Load a WASM module from bytes.

validate :: VM -> IO (WasmResult ()) #

Validate the loaded WASM module.

instantiate :: VM -> IO (WasmResult ()) #

Instantiate the loaded and validated WASM module.

execute :: VM -> Text -> [WasmVal] -> IO (WasmResult [WasmVal]) #

Execute a function in the instantiated module.

executeRegistered :: VM -> Text -> Text -> [WasmVal] -> IO (WasmResult [WasmVal]) #

Execute a function from a named registered module.

Async step-by-step

asyncExecute :: VM -> Text -> [WasmVal] -> IO Async #

Async variant of execute.

asyncExecuteRegistered :: VM -> Text -> Text -> [WasmVal] -> IO Async #

Async variant of executeRegistered.

Query

getFunctionType :: VM -> Text -> IO (Maybe FunctionType) #

Get the function type of an exported function.

getFunctionTypeRegistered :: VM -> Text -> Text -> IO (Maybe FunctionType) #

Get the function type of a function in a registered module.

cleanup :: VM -> IO () #

Clean up the VM (unload the current module without deleting the VM).

getStore :: VM -> IO Store #

Get the shared Store from the VM (borrowed — do NOT delete it).

getStatistics :: VM -> IO Statistics #

Get the statistics context from the VM (borrowed).

listRegisteredModules :: VM -> IO [Text] #

List all registered module names.

deleteRegisteredModule :: VM -> Text -> IO () #

Delete a registered module from the VM by name (0.18+).