linker.h File Reference

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

Go to the source code of this file.

Typedefs
typedef struct wasmtime_linker	wasmtime_linker_t
	Alias to wasmtime_linker.

Functions
wasmtime_linker_t *	wasmtime_linker_new (wasm_engine_t *engine)
	Creates a new linker for the specified engine. More...
wasmtime_linker_t *	wasmtime_linker_clone (wasmtime_linker_t *linker)
	Clones existing linker. More...
void	wasmtime_linker_delete (wasmtime_linker_t *linker)
	Deletes a linker.
void	wasmtime_linker_allow_shadowing (wasmtime_linker_t *linker, bool allow_shadowing)
	Configures whether this linker allows later definitions to shadow previous definitions. More...
wasmtime_error_t *	wasmtime_linker_define (wasmtime_linker_t *linker, wasmtime_context_t *store, const char *module, size_t module_len, const char *name, size_t name_len, const wasmtime_extern_t *item)
	Defines a new item in this linker. More...
wasmtime_error_t *	wasmtime_linker_define_func (wasmtime_linker_t *linker, const char *module, size_t module_len, const char *name, size_t name_len, const wasm_functype_t *ty, wasmtime_func_callback_t cb, void *data, void(*finalizer)(void *))
	Defines a new function in this linker. More...
wasmtime_error_t *	wasmtime_linker_define_func_unchecked (wasmtime_linker_t *linker, const char *module, size_t module_len, const char *name, size_t name_len, const wasm_functype_t *ty, wasmtime_func_unchecked_callback_t cb, void *data, void(*finalizer)(void *))
	Defines a new function in this linker. More...
wasmtime_error_t *	wasmtime_linker_define_wasi (wasmtime_linker_t *linker)
	Defines WASI functions in this linker. More...
wasmtime_error_t *	wasmtime_linker_define_instance (wasmtime_linker_t *linker, wasmtime_context_t *store, const char *name, size_t name_len, const wasmtime_instance_t *instance)
	Defines an instance under the specified name in this linker. More...
wasmtime_error_t *	wasmtime_linker_instantiate (const wasmtime_linker_t *linker, wasmtime_context_t *store, const wasmtime_module_t *module, wasmtime_instance_t *instance, wasm_trap_t **trap)
	Instantiates a wasm_module_t with the items defined in this linker. More...
wasmtime_error_t *	wasmtime_linker_module (wasmtime_linker_t *linker, wasmtime_context_t *store, const char *name, size_t name_len, const wasmtime_module_t *module)
	Defines automatic instantiations of a wasm_module_t in this linker. More...
wasmtime_error_t *	wasmtime_linker_get_default (const wasmtime_linker_t *linker, wasmtime_context_t *store, const char *name, size_t name_len, wasmtime_func_t *func)
	Acquires the "default export" of the named module in this linker. More...
bool	wasmtime_linker_get (const wasmtime_linker_t *linker, wasmtime_context_t *store, const char *module, size_t module_len, const char *name, size_t name_len, wasmtime_extern_t *item)
	Loads an item by name from this linker. More...
wasmtime_error_t *	wasmtime_linker_instantiate_pre (const wasmtime_linker_t *linker, const wasmtime_module_t *module, wasmtime_instance_pre_t **instance_pre)
	Preform all the checks for instantiating module with the linker, except that instantiation doesn't actually finish. More...

Detailed Description

Wasmtime API for a name-based linker used to instantiate modules.

Function Documentation

wasmtime_linker_allow_shadowing()

void wasmtime_linker_allow_shadowing	(	wasmtime_linker_t *	linker,
		bool	allow_shadowing
	)

Configures whether this linker allows later definitions to shadow previous definitions.

By default this setting is false.

wasmtime_linker_clone()

wasmtime_linker_t * wasmtime_linker_clone

(

wasmtime_linker_t *

linker

)

Clones existing linker.

This function does not take ownership of the linker argument, and the caller is expected to delete the returned linker.

wasmtime_linker_define()

wasmtime_error_t * wasmtime_linker_define	(	wasmtime_linker_t *	linker,
		wasmtime_context_t *	store,
		const char *	module,
		size_t	module_len,
		const char *	name,
		size_t	name_len,
		const wasmtime_extern_t *	item
	)

Defines a new item in this linker.

Parameters

linker	the linker the name is being defined in.
store	the store that the item is owned by.
module	the module name the item is defined under.
module_len	the byte length of module
name	the field name the item is defined under
name_len	the byte length of name
item	the item that is being defined in this linker.

Returns

On success NULL is returned, otherwise an error is returned which describes why the definition failed.

For more information about name resolution consult the Rust documentation.

wasmtime_linker_define_func()

wasmtime_error_t * wasmtime_linker_define_func	(	wasmtime_linker_t *	linker,
		const char *	module,
		size_t	module_len,
		const char *	name,
		size_t	name_len,
		const wasm_functype_t *	ty,
		wasmtime_func_callback_t	cb,
		void *	data,
		void(*)(void *)	finalizer
	)

Defines a new function in this linker.

Parameters

linker	the linker the name is being defined in.
module	the module name the item is defined under.
module_len	the byte length of module
name	the field name the item is defined under
name_len	the byte length of name
ty	the type of the function that's being defined
cb	the host callback to invoke when the function is called
data	the host-provided data to provide as the first argument to the callback
finalizer	an optional finalizer for the data argument.

Returns

On success NULL is returned, otherwise an error is returned which describes why the definition failed.

For more information about name resolution consult the Rust documentation.

Note that this function does not create a wasmtime_func_t. This creates a store-independent function within the linker, allowing this function definition to be used with multiple stores.

For more information about host callbacks see wasmtime_func_new.

wasmtime_linker_define_func_unchecked()

wasmtime_error_t * wasmtime_linker_define_func_unchecked	(	wasmtime_linker_t *	linker,
		const char *	module,
		size_t	module_len,
		const char *	name,
		size_t	name_len,
		const wasm_functype_t *	ty,
		wasmtime_func_unchecked_callback_t	cb,
		void *	data,
		void(*)(void *)	finalizer
	)

Defines a new function in this linker.

This is the same as wasmtime_linker_define_func except that it's the analog of wasmtime_func_new_unchecked instead of wasmtime_func_new. Be sure to consult the documentation of wasmtime_linker_define_func for argument information as well as wasmtime_func_new_unchecked for why this is an unsafe API.

wasmtime_linker_define_instance()

wasmtime_error_t * wasmtime_linker_define_instance	(	wasmtime_linker_t *	linker,
		wasmtime_context_t *	store,
		const char *	name,
		size_t	name_len,
		const wasmtime_instance_t *	instance
	)

Defines an instance under the specified name in this linker.

Parameters

linker	the linker the name is being defined in.
store	the store that owns instance
name	the module name to define instance under.
name_len	the byte length of name
instance	a previously-created instance.

Returns

On success NULL is returned, otherwise an error is returned which describes why the definition failed.

This function will take all of the exports of the instance provided and defined them under a module called name with a field name as the export's own name.

For more information about name resolution consult the Rust documentation.

wasmtime_linker_define_wasi()

wasmtime_error_t * wasmtime_linker_define_wasi

(

wasmtime_linker_t *

linker

)

Defines WASI functions in this linker.

Parameters

linker

the linker the name is being defined in.

Returns

On success NULL is returned, otherwise an error is returned which describes why the definition failed.

This function will provide WASI function names in the specified linker. Note that when an instance is created within a store then the store also needs to have its WASI settings configured with wasmtime_context_set_wasi for WASI functions to work, otherwise an assert will be tripped that will abort the process.

For more information about name resolution consult the Rust documentation.

wasmtime_linker_get()

bool wasmtime_linker_get	(	const wasmtime_linker_t *	linker,
		wasmtime_context_t *	store,
		const char *	module,
		size_t	module_len,
		const char *	name,
		size_t	name_len,
		wasmtime_extern_t *	item
	)

Loads an item by name from this linker.

Parameters

linker	the linker to load from
store	the store to load the item into
module	the name of the module to get
module_len	the byte length of module
name	the name of the field to get
name_len	the byte length of name
item	where to store the extracted item

Returns

A nonzero value if the item is defined, in which case item is also filled in. Otherwise zero is returned.

wasmtime_linker_get_default()

wasmtime_error_t * wasmtime_linker_get_default	(	const wasmtime_linker_t *	linker,
		wasmtime_context_t *	store,
		const char *	name,
		size_t	name_len,
		wasmtime_func_t *	func
	)

Acquires the "default export" of the named module in this linker.

Parameters

linker	the linker to load from
store	the store to load a function into
name	the name of the module to get the default export for
name_len	the byte length of name
func	where to store the extracted default function.

Returns

An error is returned if the default export could not be found, or NULL is returned and func is filled in otherwise.

For more information see the Rust documentation.

wasmtime_linker_instantiate()

wasmtime_error_t * wasmtime_linker_instantiate	(	const wasmtime_linker_t *	linker,
		wasmtime_context_t *	store,
		const wasmtime_module_t *	module,
		wasmtime_instance_t *	instance,
		wasm_trap_t **	trap
	)

Instantiates a wasm_module_t with the items defined in this linker.

Parameters

linker	the linker used to instantiate the provided module.
store	the store that is used to instantiate within
module	the module that is being instantiated.
instance	the returned instance, if successful.
trap	a trap returned, if the start function traps.

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 will attempt to satisfy all of the imports of the module provided with items previously defined in this linker. If any name isn't defined in the linker than an error is returned. (or if the previously defined item is of the wrong type).

wasmtime_linker_instantiate_pre()

wasmtime_error_t * wasmtime_linker_instantiate_pre	(	const wasmtime_linker_t *	linker,
		const wasmtime_module_t *	module,
		wasmtime_instance_pre_t **	instance_pre
	)

Preform all the checks for instantiating module with the linker, except that instantiation doesn't actually finish.

Parameters

linker	the linker used to instantiate the provided module.
module	the module that is being instantiated.
instance_pre	the returned instance_pre, if successful.

Returns

An error or NULL if successful.

For more information see the Rust documentation at: https://docs.wasmtime.dev/api/wasmtime/struct.Linker.html#method.instantiate_pre

wasmtime_linker_module()

wasmtime_error_t * wasmtime_linker_module	(	wasmtime_linker_t *	linker,
		wasmtime_context_t *	store,
		const char *	name,
		size_t	name_len,
		const wasmtime_module_t *	module
	)

Defines automatic instantiations of a wasm_module_t in this linker.

Parameters

linker	the linker the module is being added to
store	the store that is used to instantiate module
name	the name of the module within the linker
name_len	the byte length of name
module	the module that's being instantiated

Returns

An error if the module could not be instantiated or added or NULL on success.

This function automatically handles Commands and Reactors instantiation and initialization.

For more information see the Rust documentation.

wasmtime_linker_new()

wasmtime_linker_t * wasmtime_linker_new

(

wasm_engine_t *

engine

)

Creates a new linker for the specified engine.

This function does not take ownership of the engine argument, and the caller is expected to delete the returned linker.