type CompilationCache interface{api.Closer }

funcNewCompilationCache¶

func NewCompilationCache()CompilationCache

NewCompilationCache returns a new CompilationCache to be passed to RuntimeConfig.This configures only in-memory cache, and doesn't persist to the file system. See wazero.NewCompilationCacheWithDir for detail.

The returned CompilationCache can be used to share the in-memory compilation results across multiple instances of wazero.Runtime.

funcNewCompilationCacheWithDir¶

func NewCompilationCacheWithDir(dirnamestring) (CompilationCache,error)

NewCompilationCacheWithDir is like wazero.NewCompilationCache except the result also writesstate into the directory specified by `dirname` parameter.

If the dirname doesn't exist, this creates it or returns an error.

Those running wazero as a CLI or frequently restarting a process using the same wasm shoulduse this feature to reduce time waiting to compile the same module a second time.

The contents written into dirname are wazero-version specific, meaning different versions ofwazero will duplicate entries for the same input wasm.

Note: The embedder must safeguard this directory from external changes.

type CompiledModule interface {// Name returns the module name encoded into the binary or empty if not.Name()string// ImportedFunctions returns all the imported functions// (api.FunctionDefinition) in this module or nil if there are none.//// Note: Unlike ExportedFunctions, there is no unique constraint on// imports.ImportedFunctions() []api.FunctionDefinition// ExportedFunctions returns all the exported functions// (api.FunctionDefinition) in this module keyed on export name.ExportedFunctions() map[string]api.FunctionDefinition// ImportedMemories returns all the imported memories// (api.MemoryDefinition) in this module or nil if there are none.//// ## Notes//   - As of WebAssembly Core Specification 2.0, there can be at most one//     memory.//   - Unlike ExportedMemories, there is no unique constraint on imports.ImportedMemories() []api.MemoryDefinition// ExportedMemories returns all the exported memories// (api.MemoryDefinition) in this module keyed on export name.//// Note: As of WebAssembly Core Specification 2.0, there can be at most one// memory.ExportedMemories() map[string]api.MemoryDefinition// CustomSections returns all the custom sections// (api.CustomSection) in this module keyed on the section name.CustomSections() []api.CustomSection// Close releases all the allocated resources for this CompiledModule.//// Note: It is safe to call Close while having outstanding calls from an// api.Module instantiated from this.Close(context.Context)error}

type FSConfig interface {// WithDirMount assigns a directory at `dir` to any paths beginning at// `guestPath`.//// For example, `dirPath` as / (or c:\ in Windows), makes the entire host// volume writeable to the path on the guest. The `guestPath` is always a// POSIX style path, slash (/) delimited, even if run on Windows.//// If the same `guestPath` was assigned before, this overrides its value,// retaining the original precedence. See the documentation of FSConfig for// more details on `guestPath`.//// # Isolation//// The guest will have full access to this directory including escaping it// via relative path lookups like "../../". Full access includes operations// such as creating or deleting files, limited to any host level access// controls.//// # os.DirFS//// This configuration optimizes for WASI compatibility which is sometimes// at odds with the behavior of os.DirFS. Hence, this will not behave// exactly the same as os.DirFS. See /RATIONALE.md for more.WithDirMount(dir, guestPathstring)FSConfig// WithReadOnlyDirMount assigns a directory at `dir` to any paths// beginning at `guestPath`.//// This is the same as WithDirMount except only read operations are// permitted. However, escaping the directory via relative path lookups// like "../../" is still allowed.WithReadOnlyDirMount(dir, guestPathstring)FSConfig// WithFSMount assigns a fs.FS file system for any paths beginning at// `guestPath`.//// If the same `guestPath` was assigned before, this overrides its value,// retaining the original precedence. See the documentation of FSConfig for// more details on `guestPath`.//// # Isolation//// fs.FS does not restrict the ability to overwrite returned files via// io.Writer. Moreover, os.DirFS documentation includes important notes// about isolation, which also applies to fs.Sub. As of Go 1.19, the// built-in file-systems are not jailed (chroot). See//https://github.com/golang/go/issues/42322//// # os.DirFS//// Due to limited control and functionality available in os.DirFS, we// advise using WithDirMount instead. There will be behavior differences// between os.DirFS and WithDirMount, as the latter biases towards what's// expected from WASI implementations.//// # Custom fs.FileInfo//// The underlying implementation supports data not usually in fs.FileInfo// when `info.Sys` returns *sys.Stat_t. For example, a custom fs.FS can use// this approach to generate or mask sys.Inode data. Such a filesystem// needs to decorate any functions that can return fs.FileInfo:////   - `Stat` as defined on `fs.File` (always)//   - `Readdir` as defined on `os.File` (if defined)//// See sys.NewStat_t for examples.WithFSMount(fsfs.FS, guestPathstring)FSConfig}

funcNewFSConfig¶

func NewFSConfig()FSConfig

NewFSConfig returns a FSConfig that can be used for configuring module instantiation.

type HostFunctionBuilder interface {// WithGoFunction is an advanced feature for those who need higher// performance than WithFunc at the cost of more complexity.//// Here's an example addition function:////builder.WithGoFunction(api.GoFunc(func(ctx context.Context, stack []uint64) {//x, y := api.DecodeI32(stack[0]), api.DecodeI32(stack[1])//sum := x + y//stack[0] = api.EncodeI32(sum)//}), []api.ValueType{api.ValueTypeI32, api.ValueTypeI32}, []api.ValueType{api.ValueTypeI32})//// As you can see above, defining in this way implies knowledge of which// WebAssembly api.ValueType is appropriate for each parameter and result.//// See WithGoModuleFunction if you also need to access the calling module.WithGoFunction(fnapi.GoFunction, params, results []api.ValueType)HostFunctionBuilder// WithGoModuleFunction is an advanced feature for those who need higher// performance than WithFunc at the cost of more complexity.//// Here's an example addition function that loads operands from memory:////builder.WithGoModuleFunction(api.GoModuleFunc(func(ctx context.Context, m api.Module, stack []uint64) {//mem := m.Memory()//offset := api.DecodeU32(stack[0])////x, _ := mem.ReadUint32Le(ctx, offset)//y, _ := mem.ReadUint32Le(ctx, offset + 4) // 32 bits == 4 bytes!//sum := x + y////stack[0] = api.EncodeU32(sum)//}), []api.ValueType{api.ValueTypeI32}, []api.ValueType{api.ValueTypeI32})//// As you can see above, defining in this way implies knowledge of which// WebAssembly api.ValueType is appropriate for each parameter and result.//// See WithGoFunction if you don't need access to the calling module.WithGoModuleFunction(fnapi.GoModuleFunction, params, results []api.ValueType)HostFunctionBuilder// WithFunc uses reflect.Value to map a go `func` to a WebAssembly// compatible Signature. An input that isn't a `func` will fail to// instantiate.//// Here's an example of an addition function:////builder.WithFunc(func(cxt context.Context, x, y uint32) uint32 {//return x + y//})//// # Defining a function//// Except for the context.Context and optional api.Module, all parameters// or result types must map to WebAssembly numeric value types. This means// uint32, int32, uint64, int64, float32 or float64.//// api.Module may be specified as the second parameter, usually to access// memory. This is important because there are only numeric types in Wasm.// The only way to share other data is via writing memory and sharing// offsets.////builder.WithFunc(func(ctx context.Context, m api.Module, offset uint32) uint32 {//mem := m.Memory()//x, _ := mem.ReadUint32Le(ctx, offset)//y, _ := mem.ReadUint32Le(ctx, offset + 4) // 32 bits == 4 bytes!//return x + y//})//// This example propagates context properly when calling other functions// exported in the api.Module:////builder.WithFunc(func(ctx context.Context, m api.Module, offset, byteCount uint32) uint32 {//fn = m.ExportedFunction("__read")//results, err := fn(ctx, offset, byteCount)//--snip--WithFunc(interface{})HostFunctionBuilder// WithName defines the optional module-local name of this function, e.g.// "random_get"//// Note: This is not required to match the Export name.WithName(namestring)HostFunctionBuilder// WithParameterNames defines optional parameter names of the function// signature, e.x. "buf", "buf_len"//// Note: When defined, names must be provided for all parameters.WithParameterNames(names ...string)HostFunctionBuilder// WithResultNames defines optional result names of the function// signature, e.x. "errno"//// Note: When defined, names must be provided for all results.WithResultNames(names ...string)HostFunctionBuilder// Export exports this to the HostModuleBuilder as the given name, e.g.// "random_get"Export(namestring)HostModuleBuilder}

type HostModuleBuilder interface {// NewFunctionBuilder begins the definition of a host function.NewFunctionBuilder()HostFunctionBuilder// Compile returns a CompiledModule that can be instantiated by Runtime.Compile(context.Context) (CompiledModule,error)// Instantiate is a convenience that calls Compile, then Runtime.InstantiateModule.// This can fail for reasons documented on Runtime.InstantiateModule.//// Here's an example:////ctx := context.Background()//r := wazero.NewRuntime(ctx)//defer r.Close(ctx) // This closes everything this Runtime created.////hello := func() {//println("hello!")//}//env, _ := r.NewHostModuleBuilder("env").//NewFunctionBuilder().WithFunc(hello).Export("hello").//Instantiate(ctx)//// # Notes////   - Closing the Runtime has the same effect as closing the result.//   - Fields in the builder are copied during instantiation: Later changes do not affect the instantiated result.//   - To avoid using configuration defaults, use Compile instead.Instantiate(context.Context) (api.Module,error)}

type ModuleConfig interface {// WithArgs assigns command-line arguments visible to an imported function that reads an arg vector (argv). Defaults to// none. Runtime.InstantiateModule errs if any arg is empty.//// These values are commonly read by the functions like "args_get" in "wasi_snapshot_preview1" although they could be// read by functions imported from other modules.//// Similar to os.Args and exec.Cmd Env, many implementations would expect a program name to be argv[0]. However, neither// WebAssembly nor WebAssembly System Interfaces (WASI) define this. Regardless, you may choose to set the first// argument to the same value set via WithName.//// Note: This does not default to os.Args as that violates sandboxing.//// Seehttps://linux.die.net/man/3/argv andhttps://en.wikipedia.org/wiki/Null-terminated_stringWithArgs(...string)ModuleConfig// WithEnv sets an environment variable visible to a Module that imports functions. Defaults to none.// Runtime.InstantiateModule errs if the key is empty or contains a NULL(0) or equals("") character.//// Validation is the same as os.Setenv on Linux and replaces any existing value. Unlike exec.Cmd Env, this does not// default to the current process environment as that would violate sandboxing. This also does not preserve order.//// Environment variables are commonly read by the functions like "environ_get" in "wasi_snapshot_preview1" although// they could be read by functions imported from other modules.//// While similar to process configuration, there are no assumptions that can be made about anything OS-specific. For// example, neither WebAssembly nor WebAssembly System Interfaces (WASI) define concerns processes have, such as// case-sensitivity on environment keys. For portability, define entries with case-insensitively unique keys.//// Seehttps://linux.die.net/man/3/environ andhttps://en.wikipedia.org/wiki/Null-terminated_stringWithEnv(key, valuestring)ModuleConfig// WithFS is a convenience that calls WithFSConfig with an FSConfig of the// input for the root ("/") guest path.WithFS(fs.FS)ModuleConfig// WithFSConfig configures the filesystem available to each guest// instantiated with this configuration. By default, no file access is// allowed, so functions like `path_open` result in unsupported errors// (e.g. syscall.ENOSYS).WithFSConfig(FSConfig)ModuleConfig// WithName configures the module name. Defaults to what was decoded from// the name section. Duplicate names are not allowed in a single Runtime.//// Calling this with the empty string "" makes the module anonymous.// That is useful when you want to instantiate the same CompiledModule multiple times like below://// for i := 0; i < N; i++ {//// Instantiate a new Wasm module from the already compiled `compiledWasm` anonymously without a name.//instance, err := r.InstantiateModule(ctx, compiledWasm, wazero.NewModuleConfig().WithName(""))//// ....//}//// See the `concurrent-instantiation` example for a complete usage.//// Non-empty named modules are available for other modules to import by name.WithName(string)ModuleConfig// WithStartFunctions configures the functions to call after the module is// instantiated. Defaults to "_start".//// Clearing the default is supported, via `WithStartFunctions()`.//// # Notes////   - If a start function doesn't exist, it is skipped. However, any that//     do exist are called in order.//   - Start functions are not intended to be called multiple times.//     Functions that should be called multiple times should be invoked//     manually via api.Module's `ExportedFunction` method.//   - Start functions commonly exit the module during instantiation,//     preventing use of any functions later. This is the case in "wasip1",//     which defines the default value "_start".//   - See /RATIONALE.md for motivation of this feature.WithStartFunctions(...string)ModuleConfig// WithStderr configures where standard error (file descriptor 2) is written. Defaults to io.Discard.//// This writer is most commonly used by the functions like "fd_write" in "wasi_snapshot_preview1" although it could// be used by functions imported from other modules.//// # Notes////   - The caller is responsible to close any io.Writer they supply: It is not closed on api.Module Close.//   - This does not default to os.Stderr as that both violates sandboxing and prevents concurrent modules.//// Seehttps://linux.die.net/man/3/stderrWithStderr(io.Writer)ModuleConfig// WithStdin configures where standard input (file descriptor 0) is read. Defaults to return io.EOF.//// This reader is most commonly used by the functions like "fd_read" in "wasi_snapshot_preview1" although it could// be used by functions imported from other modules.//// # Notes////   - The caller is responsible to close any io.Reader they supply: It is not closed on api.Module Close.//   - This does not default to os.Stdin as that both violates sandboxing and prevents concurrent modules.//// Seehttps://linux.die.net/man/3/stdinWithStdin(io.Reader)ModuleConfig// WithStdout configures where standard output (file descriptor 1) is written. Defaults to io.Discard.//// This writer is most commonly used by the functions like "fd_write" in "wasi_snapshot_preview1" although it could// be used by functions imported from other modules.//// # Notes////   - The caller is responsible to close any io.Writer they supply: It is not closed on api.Module Close.//   - This does not default to os.Stdout as that both violates sandboxing and prevents concurrent modules.//// Seehttps://linux.die.net/man/3/stdoutWithStdout(io.Writer)ModuleConfig// WithWalltime configures the wall clock, sometimes referred to as the// real time clock. sys.Walltime returns the current unix/epoch time,// seconds since midnight UTC 1 January 1970, with a nanosecond fraction.// This defaults to a fake result that increases by 1ms on each reading.//// Here's an example that uses a custom clock://moduleConfig = moduleConfig.//WithWalltime(func(context.Context) (sec int64, nsec int32) {//return clock.walltime()//}, sys.ClockResolution(time.Microsecond.Nanoseconds()))//// # Notes://   - This does not default to time.Now as that violates sandboxing.//   - This is used to implement host functions such as WASI//     `clock_time_get` with the `realtime` clock ID.//   - Use WithSysWalltime for a usable implementation.WithWalltime(sys.Walltime,sys.ClockResolution)ModuleConfig// WithSysWalltime uses time.Now for sys.Walltime with a resolution of 1us// (1000ns).//// See WithWalltimeWithSysWalltime()ModuleConfig// WithNanotime configures the monotonic clock, used to measure elapsed// time in nanoseconds. Defaults to a fake result that increases by 1ms// on each reading.//// Here's an example that uses a custom clock://moduleConfig = moduleConfig.//WithNanotime(func(context.Context) int64 {//return clock.nanotime()//}, sys.ClockResolution(time.Microsecond.Nanoseconds()))//// # Notes://   - This does not default to time.Since as that violates sandboxing.//   - This is used to implement host functions such as WASI//     `clock_time_get` with the `monotonic` clock ID.//   - Some compilers implement sleep by looping on sys.Nanotime (e.g. Go).//   - If you set this, you should probably set WithNanosleep also.//   - Use WithSysNanotime for a usable implementation.WithNanotime(sys.Nanotime,sys.ClockResolution)ModuleConfig// WithSysNanotime uses time.Now for sys.Nanotime with a resolution of 1us.//// See WithNanotimeWithSysNanotime()ModuleConfig// WithNanosleep configures the how to pause the current goroutine for at// least the configured nanoseconds. Defaults to return immediately.//// This example uses a custom sleep function://moduleConfig = moduleConfig.//WithNanosleep(func(ns int64) {//rel := unix.NsecToTimespec(ns)//remain := unix.Timespec{}//for { // loop until no more time remaining//err := unix.ClockNanosleep(unix.CLOCK_MONOTONIC, 0, &rel, &remain)//--snip--//// # Notes://   - This does not default to time.Sleep as that violates sandboxing.//   - This is used to implement host functions such as WASI `poll_oneoff`.//   - Some compilers implement sleep by looping on sys.Nanotime (e.g. Go).//   - If you set this, you should probably set WithNanotime also.//   - Use WithSysNanosleep for a usable implementation.WithNanosleep(sys.Nanosleep)ModuleConfig// WithOsyield yields the processor, typically to implement spin-wait// loops. Defaults to return immediately.//// # Notes://   - This primarily supports `sched_yield` in WASI//   - This does not default to runtime.osyield as that violates sandboxing.WithOsyield(sys.Osyield)ModuleConfig// WithSysNanosleep uses time.Sleep for sys.Nanosleep.//// See WithNanosleepWithSysNanosleep()ModuleConfig// WithRandSource configures a source of random bytes. Defaults to return a// deterministic source. You might override this with crypto/rand.Reader//// This reader is most commonly used by the functions like "random_get" in// "wasi_snapshot_preview1", "seed" in AssemblyScript standard "env", and// "getRandomData" when runtime.GOOS is "js".//// Note: The caller is responsible to close any io.Reader they supply: It// is not closed on api.Module Close.WithRandSource(io.Reader)ModuleConfig}

funcNewModuleConfig¶

func NewModuleConfig()ModuleConfig

NewModuleConfig returns a ModuleConfig that can be used for configuring module instantiation.

type Runtime interface {// Instantiate instantiates a module from the WebAssembly binary (%.wasm)// with default configuration, which notably calls the "_start" function,// if it exists.//// Here's an example://ctx := context.Background()//r := wazero.NewRuntime(ctx)//defer r.Close(ctx) // This closes everything this Runtime created.////mod, _ := r.Instantiate(ctx, wasm)//// # Notes////   - See notes on InstantiateModule for error scenarios.//   - See InstantiateWithConfig for configuration overrides.Instantiate(ctxcontext.Context, source []byte) (api.Module,error)// InstantiateWithConfig instantiates a module from the WebAssembly binary// (%.wasm) or errs for reasons including exit or validation.//// Here's an example://ctx := context.Background()//r := wazero.NewRuntime(ctx)//defer r.Close(ctx) // This closes everything this Runtime created.////mod, _ := r.InstantiateWithConfig(ctx, wasm,//wazero.NewModuleConfig().WithName("rotate"))//// # Notes////   - See notes on InstantiateModule for error scenarios.//   - If you aren't overriding defaults, use Instantiate.//   - This is a convenience utility that chains CompileModule with//     InstantiateModule. To instantiate the same source multiple times,//     use CompileModule as InstantiateModule avoids redundant decoding//     and/or compilation.InstantiateWithConfig(ctxcontext.Context, source []byte, configModuleConfig) (api.Module,error)// NewHostModuleBuilder lets you create modules out of functions defined in Go.//// Below defines and instantiates a module named "env" with one function:////ctx := context.Background()//hello := func() {//fmt.Fprintln(stdout, "hello!")//}//_, err := r.NewHostModuleBuilder("env").//NewFunctionBuilder().WithFunc(hello).Export("hello").//Instantiate(ctx, r)//// Note: empty `moduleName` is not allowed.NewHostModuleBuilder(moduleNamestring)HostModuleBuilder// CompileModule decodes the WebAssembly binary (%.wasm) or errs if invalid.// Any pre-compilation done after decoding wasm is dependent on RuntimeConfig.//// There are two main reasons to use CompileModule instead of Instantiate://   - Improve performance when the same module is instantiated multiple times under different names//   - Reduce the amount of errors that can occur during InstantiateModule.//// # Notes////   - The resulting module name defaults to what was binary from the custom name section.//   - Any pre-compilation done after decoding the source is dependent on RuntimeConfig.//// Seehttps://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#name-section%E2%91%A0CompileModule(ctxcontext.Context, binary []byte) (CompiledModule,error)// InstantiateModule instantiates the module or errs for reasons including// exit or validation.//// Here's an example://mod, _ := n.InstantiateModule(ctx, compiled, wazero.NewModuleConfig().//WithName("prod"))//// # Errors//// While CompiledModule is pre-validated, there are a few situations which// can cause an error://   - The module name is already in use.//   - The module has a table element initializer that resolves to an index//     outside the Table minimum size.//   - The module has a start function, and it failed to execute.//   - The module was compiled to WASI and exited with a non-zero exit//     code, you'll receive a sys.ExitError.//   - RuntimeConfig.WithCloseOnContextDone was enabled and a context//     cancellation or deadline triggered before a start function returned.InstantiateModule(ctxcontext.Context, compiledCompiledModule, configModuleConfig) (api.Module,error)// CloseWithExitCode closes all the modules that have been initialized in this Runtime with the provided exit code.// An error is returned if any module returns an error when closed.//// Here's an example://ctx := context.Background()//r := wazero.NewRuntime(ctx)//defer r.CloseWithExitCode(ctx, 2) // This closes everything this Runtime created.////// Everything below here can be closed, but will anyway due to above.//_, _ = wasi_snapshot_preview1.InstantiateSnapshotPreview1(ctx, r)//mod, _ := r.Instantiate(ctx, wasm)CloseWithExitCode(ctxcontext.Context, exitCodeuint32)error// Module returns an instantiated module in this runtime or nil if there aren't any.Module(moduleNamestring)api.Module// Closer closes all compiled code by delegating to CloseWithExitCode with an exit code of zero.api.Closer}

funcNewRuntime¶

func NewRuntime(ctxcontext.Context)Runtime

NewRuntime returns a runtime with a configuration assigned by NewRuntimeConfig.

funcNewRuntimeWithConfig¶

func NewRuntimeWithConfig(ctxcontext.Context, rConfigRuntimeConfig)Runtime

NewRuntimeWithConfig returns a runtime with the given configuration.

type RuntimeConfig interface {// WithCoreFeatures sets the WebAssembly Core specification features this// runtime supports. Defaults to api.CoreFeaturesV2.//// Example of disabling a specific feature://features := api.CoreFeaturesV2.SetEnabled(api.CoreFeatureMutableGlobal, false)//rConfig = wazero.NewRuntimeConfig().WithCoreFeatures(features)//// # Why default to version 2.0?//// Many compilers that target WebAssembly require features after// api.CoreFeaturesV1 by default. For example, TinyGo v0.24+ requires// api.CoreFeatureBulkMemoryOperations. To avoid runtime errors, wazero// defaults to api.CoreFeaturesV2, even though it is not yet a Web// Standard (REC).WithCoreFeatures(api.CoreFeatures)RuntimeConfig// WithMemoryLimitPages overrides the maximum pages allowed per memory. The// default is 65536, allowing 4GB total memory per instance if the maximum is// not encoded in a Wasm binary. Setting a value larger than default will panic.//// This example reduces the largest possible memory size from 4GB to 128KB://rConfig = wazero.NewRuntimeConfig().WithMemoryLimitPages(2)//// Note: Wasm has 32-bit memory and each page is 65536 (2^16) bytes. This// implies a max of 65536 (2^16) addressable pages.// Seehttps://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#grow-memWithMemoryLimitPages(memoryLimitPagesuint32)RuntimeConfig// WithMemoryCapacityFromMax eagerly allocates max memory, unless max is// not defined. The default is false, which means minimum memory is// allocated and any call to grow memory results in re-allocations.//// This example ensures any memory.grow instruction will never re-allocate://rConfig = wazero.NewRuntimeConfig().WithMemoryCapacityFromMax(true)//// Seehttps://www.w3.org/TR/2019/REC-wasm-core-1-20191205/#grow-mem//// Note: if the memory maximum is not encoded in a Wasm binary, this// results in allocating 4GB. See the doc on WithMemoryLimitPages for detail.WithMemoryCapacityFromMax(memoryCapacityFromMaxbool)RuntimeConfig// WithDebugInfoEnabled toggles DWARF based stack traces in the face of// runtime errors. Defaults to true.//// Those who wish to disable this, can like so:////r := wazero.NewRuntimeWithConfig(wazero.NewRuntimeConfig().WithDebugInfoEnabled(false)//// When disabled, a stack trace message looks like:////wasm stack trace://.runtime._panic(i32)//.myFunc()//.main.main()//.runtime.run()//._start()//// When enabled, the stack trace includes source code information:////wasm stack trace://.runtime._panic(i32)//  0x16e2: /opt/homebrew/Cellar/tinygo/0.26.0/src/runtime/runtime_tinygowasm.go:73:6//.myFunc()//  0x190b: /Users/XXXXX/wazero/internal/testing/dwarftestdata/testdata/main.go:19:7//.main.main()//  0x18ed: /Users/XXXXX/wazero/internal/testing/dwarftestdata/testdata/main.go:4:3//.runtime.run()//  0x18cc: /opt/homebrew/Cellar/tinygo/0.26.0/src/runtime/scheduler_none.go:26:10//._start()//  0x18b6: /opt/homebrew/Cellar/tinygo/0.26.0/src/runtime/runtime_wasm_wasi.go:22:5//// Note: This only takes into effect when the original Wasm binary has the// DWARF "custom sections" that are often stripped, depending on// optimization flags passed to the compiler.WithDebugInfoEnabled(bool)RuntimeConfig// WithCompilationCache configures how runtime caches the compiled modules. In the default configuration, compilation results are// only in-memory until Runtime.Close is closed, and not shareable by multiple Runtime.//// Below defines the shared cache across multiple instances of Runtime:////// Creates the new Cache and the runtime configuration with it.//cache := wazero.NewCompilationCache()//defer cache.Close()//config := wazero.NewRuntimeConfig().WithCompilationCache(c)////// Creates two runtimes while sharing compilation caches.//foo := wazero.NewRuntimeWithConfig(context.Background(), config)// bar := wazero.NewRuntimeWithConfig(context.Background(), config)//// # Cache Key//// Cached files are keyed on the version of wazero. This is obtained from go.mod of your application,// and we use it to verify the compatibility of caches against the currently-running wazero.// However, if you use this in tests of a package not named as `main`, then wazero cannot obtain the correct// version of wazero due to the known issue of debug.BuildInfo function:https://github.com/golang/go/issues/33976.// As a consequence, your cache won't contain the correct version information and always be treated as `dev` version.// To avoid this issue, you can pass -ldflags "-X github.com/tetratelabs/wazero/internal/version.version=foo" when running tests.WithCompilationCache(CompilationCache)RuntimeConfig// WithCustomSections toggles parsing of "custom sections". Defaults to false.//// When enabled, it is possible to retrieve custom sections from a CompiledModule:////config := wazero.NewRuntimeConfig().WithCustomSections(true)//r := wazero.NewRuntimeWithConfig(ctx, config)//c, err := r.CompileModule(ctx, wasm)//customSections := c.CustomSections()WithCustomSections(bool)RuntimeConfig// WithCloseOnContextDone ensures the executions of functions to be terminated under one of the following circumstances://// - context.Context passed to the Call method of api.Function is canceled during execution. (i.e. ctx by context.WithCancel)// - context.Context passed to the Call method of api.Function reaches timeout during execution. (i.e. ctx by context.WithTimeout or context.WithDeadline)// - Close or CloseWithExitCode of api.Module is explicitly called during execution.//// This is especially useful when one wants to run untrusted Wasm binaries since otherwise, any invocation of// api.Function can potentially block the corresponding Goroutine forever. Moreover, it might block the// entire underlying OS thread which runs the api.Function call. See "Why it's safe to execute runtime-generated// machine codes against async Goroutine preemption" section in RATIONALE.md for detail.//// Upon the termination of the function executions, api.Module is closed.//// Note that this comes with a bit of extra cost when enabled. The reason is that internally this forces// interpreter and compiler runtimes to insert the periodical checks on the conditions above. For that reason,// this is disabled by default.//// See examples in context_done_example_test.go for the end-to-end demonstrations.//// When the invocations of api.Function are closed due to this, sys.ExitError is raised to the callers and// the api.Module from which the functions are derived is made closed.WithCloseOnContextDone(bool)RuntimeConfig}

funcNewRuntimeConfig¶

func NewRuntimeConfig()RuntimeConfig

NewRuntimeConfig returns a RuntimeConfig using the compiler if it is supported in this environment,or the interpreter otherwise.

funcNewRuntimeConfigCompiler¶

func NewRuntimeConfigCompiler()RuntimeConfig

NewRuntimeConfigCompiler compiles WebAssembly modules intoruntime.GOARCH-specific assembly for optimal performance.

The default implementation is AOT (Ahead of Time) compilation, applied atRuntime.CompileModule. This allows consistent runtime performance, as wellthe ability to reduce any first request penalty.

Note: While this is technically AOT, this does not imply any action on yourpart. wazero automatically performs ahead-of-time compilation as needed whenRuntime.CompileModule is invoked.

Warning¶

• This panics at runtime if the runtime.GOOS or runtime.GOARCH does notsupport compiler. Use NewRuntimeConfig to safely detect and fallback toNewRuntimeConfigInterpreter if needed.

• If you are using wazero in buildmode=c-archive or c-shared, make sure that you set up the alternate signal stackby using, e.g. `sigaltstack` combined with `SA_ONSTACK` flag on `sigaction` on Linux,before calling any api.Function. This is because the Go runtime does not set up the alternate signal stackfor c-archive or c-shared modes, and wazero uses the different stack than the calling Goroutine.Hence, the signal handler might get invoked on the wazero's stack, which may cause a stack overflow.https://github.com/tetratelabs/wazero/blob/2092c0a879f30d49d7b37f333f4547574b8afe0d/internal/integration_test/fuzz/fuzz/tests/sigstack.rs#L19-L36

funcNewRuntimeConfigInterpreter¶

func NewRuntimeConfigInterpreter()RuntimeConfig

NewRuntimeConfigInterpreter interprets WebAssembly modules instead of compiling them into assembly.