Wasmtime
linker.h File Reference
#include <wasm.h>
#include <wasmtime/error.h>
#include <wasmtime/store.h>
#include <wasmtime/extern.h>

Go to the source code of this file.

Typedefs

typedef struct wasmtime_linker wasmtime_linker_t
 Alias to wasmtime_linker.
 

Functions

wasmtime_linker_twasmtime_linker_new (wasm_engine_t *engine)
 Creates a new linker for the specified engine. 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_twasmtime_linker_define (wasmtime_linker_t *linker, 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_twasmtime_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_twasmtime_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_twasmtime_linker_define_wasi (wasmtime_linker_t *linker)
 Defines WASI functions in this linker. More...
 
wasmtime_error_twasmtime_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_twasmtime_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_twasmtime_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_twasmtime_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...
 

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_define()

wasmtime_error_t * wasmtime_linker_define ( wasmtime_linker_t linker,
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
linkerthe linker the name is being defined in.
modulethe module name the item is defined under.
module_lenthe byte length of module
namethe field name the item is defined under
name_lenthe byte length of name
itemthe 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
linkerthe linker the name is being defined in.
modulethe module name the item is defined under.
module_lenthe byte length of module
namethe field name the item is defined under
name_lenthe byte length of name
tythe type of the function that's being defined
cbthe host callback to invoke when the function is called
datathe host-provided data to provide as the first argument to the callback
finalizeran 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
linkerthe linker the name is being defined in.
storethe store that owns instance
namethe module name to define instance under.
name_lenthe byte length of name
instancea 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
linkerthe 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
linkerthe linker to load from
storethe store to load the item into
modulethe name of the module to get
module_lenthe byte length of module
namethe name of the field to get
name_lenthe byte length of name
itemwhere 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
linkerthe linker to load from
storethe store to load a function into
namethe name of the module to get the default export for
name_lenthe byte length of name
funcwhere 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
linkerthe linker used to instantiate the provided module.
storethe store that is used to instantiate within
modulethe module that is being instantiated.
instancethe returned instance, if successful.
trapa 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_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
linkerthe linker the module is being added to
storethe store that is used to instantiate module
namethe name of the module within the linker
name_lenthe byte length of name
modulethe 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.