instance.h File Reference

#include <wasm.h>
#include <wasmtime/extern.h>
#include <wasmtime/module.h>
#include <wasmtime/store.h>

Go to the source code of this file.

Data Structures
struct	wasmtime_instance
	Representation of a instance in Wasmtime. More...

Typedefs
typedef struct wasmtime_instance	wasmtime_instance_t
	Representation of a instance in Wasmtime. More...
typedef struct wasmtime_instance_pre	wasmtime_instance_pre_t
	A wasmtime_instance_t, pre-instantiation, that is ready to be instantiated. More...

Functions
wasmtime_error_t *	wasmtime_instance_new (wasmtime_context_t *store, const wasmtime_module_t *module, const wasmtime_extern_t *imports, size_t nimports, wasmtime_instance_t *instance, wasm_trap_t **trap)
	Instantiate a wasm module. More...
bool	wasmtime_instance_export_get (wasmtime_context_t *store, const wasmtime_instance_t *instance, const char *name, size_t name_len, wasmtime_extern_t *item)
	Get an export by name from an instance. More...
bool	wasmtime_instance_export_nth (wasmtime_context_t *store, const wasmtime_instance_t *instance, size_t index, char **name, size_t *name_len, wasmtime_extern_t *item)
	Get an export by index from an instance. More...
void	wasmtime_instance_pre_delete (wasmtime_instance_pre_t *instance_pre)
	Delete a previously created wasmtime_instance_pre_t.
wasmtime_error_t *	wasmtime_instance_pre_instantiate (const wasmtime_instance_pre_t *instance_pre, wasmtime_store_t *store, wasmtime_instance_t *instance, wasm_trap_t **trap_ptr)
	Instantiates instance within the given store. More...
wasmtime_module_t *	wasmtime_instance_pre_module (wasmtime_instance_pre_t *instance_pre)
	Get the module (as a shallow clone) for a instance_pre. More...

Detailed Description

Wasmtime APIs for interacting with wasm instances.

Typedef Documentation

wasmtime_instance_pre_t

typedef struct wasmtime_instance_pre wasmtime_instance_pre_t

A wasmtime_instance_t, pre-instantiation, that is ready to be instantiated.

Must be deleted using wasmtime_instance_pre_delete.

For more information see the Rust documentation: https://docs.wasmtime.dev/api/wasmtime/struct.InstancePre.html

wasmtime_instance_t

typedef struct wasmtime_instance wasmtime_instance_t

Representation of a instance in Wasmtime.

Instances are represented with a 64-bit identifying integer in Wasmtime. They do not have any destructor associated with them. Instances cannot interoperate between wasmtime_store_t instances and if the wrong instance is passed to the wrong store then it may trigger an assertion to abort the process.

Function Documentation

wasmtime_instance_export_get()

bool wasmtime_instance_export_get	(	wasmtime_context_t *	store,
		const wasmtime_instance_t *	instance,
		const char *	name,
		size_t	name_len,
		wasmtime_extern_t *	item
	)

Get an export by name from an instance.

Parameters

store	the store that owns instance
instance	the instance to lookup within
name	the export name to lookup
name_len	the byte length of name
item	where to store the returned value

Returns nonzero if the export was found, and item is filled in. Otherwise returns 0.

Doesn't take ownership of any arguments but does return ownership of the wasmtime_extern_t.

wasmtime_instance_export_nth()

bool wasmtime_instance_export_nth	(	wasmtime_context_t *	store,
		const wasmtime_instance_t *	instance,
		size_t	index,
		char **	name,
		size_t *	name_len,
		wasmtime_extern_t *	item
	)

Get an export by index from an instance.

Parameters

store	the store that owns instance
instance	the instance to lookup within
index	the index to lookup
name	where to store the name of the export
name_len	where to store the byte length of the name
item	where to store the export itself

Returns nonzero if the export was found, and name, name_len, and item are filled in. Otherwise returns 0.

Doesn't take ownership of any arguments but does return ownership of the wasmtime_extern_t. The name pointer return value is owned by the store and must be immediately used before calling any other APIs on wasmtime_context_t.

wasmtime_instance_new()

wasmtime_error_t * wasmtime_instance_new	(	wasmtime_context_t *	store,
		const wasmtime_module_t *	module,
		const wasmtime_extern_t *	imports,
		size_t	nimports,
		wasmtime_instance_t *	instance,
		wasm_trap_t **	trap
	)

Instantiate a wasm module.

This function will instantiate a WebAssembly module with the provided imports, creating a WebAssembly instance. The returned instance can then afterwards be inspected for exports.

Parameters

store	the store in which to create the instance
module	the module that's being instantiated
imports	the imports provided to the module
nimports	the size of imports
instance	where to store the returned instance
trap	where to store the returned trap

This function requires that imports is the same size as the imports that module has. Additionally the imports array must be 1:1 lined up with the imports of the module specified. This is intended to be relatively low level, and wasmtime_linker_instantiate is provided for a more ergonomic name-based resolution API.

The states of return values from this function are similar to wasmtime_func_call where an error can be returned meaning something like a link error in this context. A trap can be returned (meaning no error or instance is returned), or an instance can be returned (meaning no error or trap is returned).

Note that this function requires that all imports specified must be owned by the store provided as well.

This function does not take ownership of any of its arguments, but all return values are owned by the caller.

wasmtime_instance_pre_instantiate()

wasmtime_error_t * wasmtime_instance_pre_instantiate	(	const wasmtime_instance_pre_t *	instance_pre,
		wasmtime_store_t *	store,
		wasmtime_instance_t *	instance,
		wasm_trap_t **	trap_ptr
	)

Instantiates instance within the given store.

This will also run the function's startup function, if there is one.

For more information on instantiation see wasmtime_instance_new.

Parameters

instance_pre	the pre-initialized instance
store	the store in which to create the instance
instance	where to store the returned instance
trap_ptr	where to store the returned trap

Returns

One of three things can happen as a result of this function. First the module could be successfully instantiated and returned through instance, meaning the return value and trap are both set to NULL. Second the start function may trap, meaning the return value and instance are set to NULL and trap describes the trap that happens. Finally instantiation may fail for another reason, in which case an error is returned and trap and instance are set to NULL.

This function does not take ownership of any of its arguments, and all return values are owned by the caller.

wasmtime_instance_pre_module()

wasmtime_module_t * wasmtime_instance_pre_module

(

wasmtime_instance_pre_t *

instance_pre

)

Get the module (as a shallow clone) for a instance_pre.

The returned module is owned by the caller and the caller must delete it via wasmtime_module_delete.