component/linker.h File Reference

#include <wasm.h>
#include <wasmtime/async.h>
#include <wasmtime/component/component.h>
#include <wasmtime/component/instance.h>
#include <wasmtime/component/types/func.h>
#include <wasmtime/conf.h>
#include <wasmtime/error.h>
#include <wasmtime/module.h>
#include <wasmtime/store.h>

Go to the source code of this file.

Typedefs
typedef struct wasmtime_component_linker_t	wasmtime_component_linker_t
	A type used to instantiate a wasmtime_component_t.
typedef struct wasmtime_component_linker_instance_t	wasmtime_component_linker_instance_t
	Structure representing an "instance" being defined within a linker.
typedef wasmtime_error_t *(*	wasmtime_component_func_callback_t) (void *, wasmtime_context_t *, const wasmtime_component_func_type_t *, wasmtime_component_val_t *, size_t, wasmtime_component_val_t *, size_t)
	Type of the callback used in wasmtime_component_linker_instance_add_func.
typedef wasmtime_error_t *(*	wasmtime_component_resource_destructor_t) (void *, wasmtime_context_t *, uint32_t)
typedef void(*	wasmtime_component_func_async_callback_t) (void *env, wasmtime_context_t *context, const wasmtime_component_func_type_t *ty, wasmtime_component_val_t *args, size_t nargs, wasmtime_component_val_t *results, size_t nresults, wasmtime_error_t **error_ret, wasmtime_async_continuation_t *continuation_ret)

Functions
WASM_API_EXTERN wasmtime_component_linker_t *	wasmtime_component_linker_new (const wasm_engine_t *engine)
	Creates a new wasmtime_component_linker_t for the specified engine. More...
WASM_API_EXTERN void	wasmtime_component_linker_allow_shadowing (wasmtime_component_linker_t *linker, bool allow)
	Configures whether this linker allows later definitions to shadow previous definitions. More...
WASM_API_EXTERN wasmtime_component_linker_instance_t *	wasmtime_component_linker_root (wasmtime_component_linker_t *linker)
	Returns the "root instance" of this linker, used to define names into the root namespace. More...
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_linker_instantiate (const wasmtime_component_linker_t *linker, wasmtime_context_t *context, const wasmtime_component_t *component, wasmtime_component_instance_t *instance_out)
	Instantiates a component instance in a given wasmtime_context_t. More...
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_linker_define_unknown_imports_as_traps (wasmtime_component_linker_t *linker, const wasmtime_component_t *component)
	Defines all unknown imports of component as trapping functions.
WASM_API_EXTERN void	wasmtime_component_linker_delete (wasmtime_component_linker_t *linker)
	Deletes a wasmtime_component_linker_t created by wasmtime_component_linker_new. More...
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_linker_instance_add_instance (wasmtime_component_linker_instance_t *linker_instance, const char *name, size_t name_len, wasmtime_component_linker_instance_t **linker_instance_out)
	Defines a nested instance within this instance. More...
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_linker_instance_add_module (wasmtime_component_linker_instance_t *linker_instance, const char *name, size_t name_len, const wasmtime_module_t *module)
	Defines a wasmtime_module_t within this instance. More...
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_linker_instance_add_func (wasmtime_component_linker_instance_t *linker_instance, const char *name, size_t name_len, wasmtime_component_func_callback_t callback, void *data, void(*finalizer)(void *))
	Define a function within this instance. More...
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_linker_add_wasip2 (wasmtime_component_linker_t *linker)
	Add all WASI interfaces into the linker provided.
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_linker_add_wasi_http (wasmtime_component_linker_t *linker)
	Add WASI HTTP interfaces into the linker provided. More...
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_linker_instance_add_resource (wasmtime_component_linker_instance_t *linker_instance, const char *name, size_t name_len, const wasmtime_component_resource_type_t *resource, wasmtime_component_resource_destructor_t destructor, void *data, void(*finalizer)(void *))
	Defines a new resource type within this instance. More...
WASM_API_EXTERN void	wasmtime_component_linker_instance_delete (wasmtime_component_linker_instance_t *linker_instance)
	Deletes a wasmtime_component_linker_instance_t. More...
WASM_API_EXTERN wasmtime_call_future_t *	wasmtime_component_linker_instantiate_async (const wasmtime_component_linker_t *linker, wasmtime_context_t *context, const wasmtime_component_t *component, wasmtime_component_instance_t *instance_out, wasmtime_error_t **error_ret)
	Instantiate a component in linker asynchronously. More...
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_linker_instance_add_func_async (wasmtime_component_linker_instance_t *linker_instance, const char *name, size_t name_len, wasmtime_component_func_async_callback_t callback, void *data, void(*finalizer)(void *))
	Define an async function within this instance. More...
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_linker_add_wasip2_async (wasmtime_component_linker_t *linker)
	Add all WASI interfaces into the linker provided using async bindings.
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_linker_add_wasi_http_async (wasmtime_component_linker_t *linker)
	Add WASI HTTP interfaces into the linker provided using async bindings.

Typedef Documentation

wasmtime_component_func_async_callback_t

typedef void(* wasmtime_component_func_async_callback_t) (void *env, wasmtime_context_t *context, const wasmtime_component_func_type_t *ty, wasmtime_component_val_t *args, size_t nargs, wasmtime_component_val_t *results, size_t nresults, wasmtime_error_t **error_ret, wasmtime_async_continuation_t *continuation_ret)

Type of the async callback used in wasmtime_component_linker_instance_add_func_async

wasmtime_component_resource_destructor_t

typedef wasmtime_error_t *(* wasmtime_component_resource_destructor_t) (void *, wasmtime_context_t *, uint32_t)

Type of the callback used in wasmtime_component_linker_instance_add_resource

Function Documentation

wasmtime_component_linker_add_wasi_http()

WASM_API_EXTERN wasmtime_error_t * wasmtime_component_linker_add_wasi_http

(

wasmtime_component_linker_t *

linker

)

Add WASI HTTP interfaces into the linker provided.

This adds wasi:http/types and wasi:http/outgoing-handler to the linker. Requires WASI to be added first via wasmtime_component_linker_add_wasip2.

wasmtime_component_linker_allow_shadowing()

WASM_API_EXTERN void wasmtime_component_linker_allow_shadowing	(	wasmtime_component_linker_t *	linker,
		bool	allow
	)

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

By default this setting is false.

wasmtime_component_linker_delete()

WASM_API_EXTERN void wasmtime_component_linker_delete

(

wasmtime_component_linker_t *

linker

)

Deletes a wasmtime_component_linker_t created by wasmtime_component_linker_new.

Parameters

linker

the wasmtime_component_linker_t to delete

wasmtime_component_linker_instance_add_func()

WASM_API_EXTERN wasmtime_error_t * wasmtime_component_linker_instance_add_func	(	wasmtime_component_linker_instance_t *	linker_instance,
		const char *	name,
		size_t	name_len,
		wasmtime_component_func_callback_t	callback,
		void *	data,
		void(*)(void *)	finalizer
	)

Define a function within this instance.

Parameters

linker_instance	the instance to define the function in
name	the module name
name_len	length of name in bytes
callback	the callback when this function gets called
data	host-specific data passed to the callback invocation, can be NULL
finalizer	optional finalizer for data, can be NULL

Returns

on success NULL, otherwise an error

wasmtime_component_linker_instance_add_func_async()

WASM_API_EXTERN wasmtime_error_t * wasmtime_component_linker_instance_add_func_async	(	wasmtime_component_linker_instance_t *	linker_instance,
		const char *	name,
		size_t	name_len,
		wasmtime_component_func_async_callback_t	callback,
		void *	data,
		void(*)(void *)	finalizer
	)

Define an async function within this instance.

This is the same as wasmtime_component_linker_instance_add_func except that it supports async callbacks.

Parameters

linker_instance	the instance to define the function in
name	the function name
name_len	length of name in bytes
callback	the async callback when this function gets called
data	host-specific data passed to the callback invocation, can be NULL
finalizer	optional finalizer for data, can be NULL

Returns

on success NULL, otherwise an error

wasmtime_component_linker_instance_add_instance()

WASM_API_EXTERN wasmtime_error_t * wasmtime_component_linker_instance_add_instance	(	wasmtime_component_linker_instance_t *	linker_instance,
		const char *	name,
		size_t	name_len,
		wasmtime_component_linker_instance_t **	linker_instance_out
	)

Defines a nested instance within this instance.

This can be used to describe arbitrarily nested levels of instances within a linker to satisfy nested instance exports of components.

Warning

This acquires exclusive access to the linker_instance. The linker_instance MUST not be accessed by anything until the returned wasmtime_component_linker_instance_t in linker_instance_out is destroyed by wasmtime_component_linker_instance_delete.

Parameters

linker_instance	the linker instance from which the new one is created
name	new instance name
name_len	length of name in bytes
linker_instance_out	on success, the new wasmtime_component_linker_instance_t

Returns

on success NULL, otherwise an error

wasmtime_component_linker_instance_add_module()

WASM_API_EXTERN wasmtime_error_t * wasmtime_component_linker_instance_add_module	(	wasmtime_component_linker_instance_t *	linker_instance,
		const char *	name,
		size_t	name_len,
		const wasmtime_module_t *	module
	)

Defines a wasmtime_module_t within this instance.

This can be used to provide a core wasm wasmtime_module_t as an import to a component. The wasmtime_module_t provided is saved within the linker for the specified name in this instance.

Parameters

linker_instance	the instance to define the module in
name	the module name
name_len	length of name in bytes
module	the module

Returns

on success NULL, otherwise an error

wasmtime_component_linker_instance_add_resource()

WASM_API_EXTERN wasmtime_error_t * wasmtime_component_linker_instance_add_resource	(	wasmtime_component_linker_instance_t *	linker_instance,
		const char *	name,
		size_t	name_len,
		const wasmtime_component_resource_type_t *	resource,
		wasmtime_component_resource_destructor_t	destructor,
		void *	data,
		void(*)(void *)	finalizer
	)

Defines a new resource type within this instance.

This can be used to define a new resource type that the guest will be able to import. Here the resource is a type, often a host-defined type, which can be used to distinguish and definite different types of resources. A destruction callback is also specified via destructor which has private data data along with an optional finalizer for the data too.

Returns

on success NULL, otherwise an error

wasmtime_component_linker_instance_delete()

WASM_API_EXTERN void wasmtime_component_linker_instance_delete

(

wasmtime_component_linker_instance_t *

linker_instance

)

Deletes a wasmtime_component_linker_instance_t.

Parameters

linker_instance

the wasmtime_component_linker_instance_t to delete

wasmtime_component_linker_instantiate()

WASM_API_EXTERN wasmtime_error_t * wasmtime_component_linker_instantiate	(	const wasmtime_component_linker_t *	linker,
		wasmtime_context_t *	context,
		const wasmtime_component_t *	component,
		wasmtime_component_instance_t *	instance_out
	)

Instantiates a component instance in a given wasmtime_context_t.

Parameters

linker	a wasmtime_component_linker_t that will help provide host functions
context	the wasmtime_context_t in which the instance should be created
component	the wasmtime_component_t to instantiate
instance_out	on success, the instantiated wasmtime_component_instance_t

Returns

wasmtime_error_t* on success NULL is returned, otherwise an error is returned which describes why the build failed.

wasmtime_component_linker_instantiate_async()

WASM_API_EXTERN wasmtime_call_future_t * wasmtime_component_linker_instantiate_async	(	const wasmtime_component_linker_t *	linker,
		wasmtime_context_t *	context,
		const wasmtime_component_t *	component,
		wasmtime_component_instance_t *	instance_out,
		wasmtime_error_t **	error_ret
	)

Instantiate a component in linker asynchronously.

This is the same as wasmtime_component_linker_instantiate except that it is asynchronous. This is only compatible with stores associated with an asynchronous config.

The result is a future that is owned by the caller and must be deleted via wasmtime_call_future_delete.

All parameters to this function must be kept alive and not modified until the returned wasmtime_call_future_t is deleted.

Parameters

linker	the linker to instantiate with
context	the store context
component	the component to instantiate
instance_out	where to store the returned instance
error_ret	where to store the returned error

wasmtime_component_linker_new()

WASM_API_EXTERN wasmtime_component_linker_t * wasmtime_component_linker_new

(

const wasm_engine_t *

engine

)

Creates a new wasmtime_component_linker_t for the specified engine.

Parameters

engine

the compilation environment and configuration

Returns

a pointer to the newly created wasmtime_component_linker_t

wasmtime_component_linker_root()

WASM_API_EXTERN wasmtime_component_linker_instance_t * wasmtime_component_linker_root

(

wasmtime_component_linker_t *

linker

)

Returns the "root instance" of this linker, used to define names into the root namespace.

Warning

This acquires exclusive access to the linker. The linker MUST not be accessed by anything until the returned wasmtime_component_linker_instance_t in linker_instance_out is destroyed by wasmtime_component_linker_instance_delete.