Wasmtime
func.h File Reference
#include <wasm.h>
#include <wasmtime/val.h>
#include <wasmtime/store.h>
#include <wasmtime/extern.h>

Go to the source code of this file.

Typedefs

typedef struct wasmtime_caller wasmtime_caller_t
 Alias to wasmtime_caller. More...
 
typedef wasm_trap_t *(* wasmtime_func_callback_t) (void *env, wasmtime_caller_t *caller, const wasmtime_val_t *args, size_t nargs, wasmtime_val_t *results, size_t nresults)
 Callback signature for wasmtime_func_new. More...
 
typedef wasm_trap_t *(* wasmtime_func_unchecked_callback_t) (void *env, wasmtime_caller_t *caller, wasmtime_val_raw_t *args_and_results, size_t num_args_and_results)
 Callback signature for wasmtime_func_new_unchecked. More...
 

Functions

void wasmtime_func_new (wasmtime_context_t *store, const wasm_functype_t *type, wasmtime_func_callback_t callback, void *env, void(*finalizer)(void *), wasmtime_func_t *ret)
 Creates a new host-defined function. More...
 
void wasmtime_func_new_unchecked (wasmtime_context_t *store, const wasm_functype_t *type, wasmtime_func_unchecked_callback_t callback, void *env, void(*finalizer)(void *), wasmtime_func_t *ret)
 Creates a new host function in the same manner of wasmtime_func_new, but the function-to-call has no type information available at runtime. More...
 
wasm_functype_twasmtime_func_type (const wasmtime_context_t *store, const wasmtime_func_t *func)
 Returns the type of the function specified. More...
 
wasmtime_error_twasmtime_func_call (wasmtime_context_t *store, const wasmtime_func_t *func, const wasmtime_val_t *args, size_t nargs, wasmtime_val_t *results, size_t nresults, wasm_trap_t **trap)
 Call a WebAssembly function. More...
 
wasm_trap_twasmtime_func_call_unchecked (wasmtime_context_t *store, const wasmtime_func_t *func, wasmtime_val_raw_t *args_and_results)
 Call a WebAssembly function in an "unchecked" fashion. More...
 
bool wasmtime_caller_export_get (wasmtime_caller_t *caller, const char *name, size_t name_len, wasmtime_extern_t *item)
 Loads a wasmtime_extern_t from the caller's context. More...
 
wasmtime_context_twasmtime_caller_context (wasmtime_caller_t *caller)
 Returns the store context of the caller object.
 
void wasmtime_func_from_raw (wasmtime_context_t *context, size_t raw, wasmtime_func_t *ret)
 Converts a raw nonzero funcref value from wasmtime_val_raw_t into a wasmtime_func_t. More...
 
size_t wasmtime_func_to_raw (wasmtime_context_t *context, const wasmtime_func_t *func)
 Converts a func which belongs to context into a usize parameter that is suitable for insertion into a wasmtime_val_raw_t.
 

Detailed Description

Wasmtime definitions of how to interact with host and wasm functions.

Typedef Documentation

◆ wasmtime_caller_t

Alias to wasmtime_caller.

Structure used to learn about the caller of a host-defined function.

◆ wasmtime_func_callback_t

typedef wasm_trap_t *(* wasmtime_func_callback_t) (void *env, wasmtime_caller_t *caller, const wasmtime_val_t *args, size_t nargs, wasmtime_val_t *results, size_t nresults)

Callback signature for wasmtime_func_new.

This is the function signature for host functions that can be made accessible to WebAssembly. The arguments to this function are:

Parameters
envuser-provided argument passed to wasmtime_func_new
callera temporary object that can only be used during this function call. Used to acquire wasmtime_context_t or caller's state
argsthe arguments provided to this function invocation
nargshow many arguments are provided
resultswhere to write the results of this function
nresultshow many results must be produced

Callbacks are guaranteed to get called with the right types of arguments, but they must produce the correct number and types of results. Failure to do so will cause traps to get raised on the wasm side.

This callback can optionally return a wasm_trap_t indicating that a trap should be raised in WebAssembly. It's expected that in this case the caller relinquishes ownership of the trap and it is passed back to the engine.

◆ wasmtime_func_unchecked_callback_t

typedef wasm_trap_t *(* wasmtime_func_unchecked_callback_t) (void *env, wasmtime_caller_t *caller, wasmtime_val_raw_t *args_and_results, size_t num_args_and_results)

Callback signature for wasmtime_func_new_unchecked.

This is the function signature for host functions that can be made accessible to WebAssembly. The arguments to this function are:

Parameters
envuser-provided argument passed to wasmtime_func_new_unchecked
callera temporary object that can only be used during this function call. Used to acquire wasmtime_context_t or caller's state
args_and_resultsstorage space for both the parameters to the function as well as the results of the function. The size of this array depends on the function type that the host function is created with, but it will be the maximum of the number of parameters and number of results.
num_args_and_resultsthe size of the args_and_results parameter in units of wasmtime_val_raw_t.

This callback can optionally return a wasm_trap_t indicating that a trap should be raised in WebAssembly. It's expected that in this case the caller relinquishes ownership of the trap and it is passed back to the engine.

This differs from wasmtime_func_callback_t in that the payload of args_and_results does not have type information, nor does it have sizing information. This is especially unsafe because it's only valid within the particular wasm_functype_t that the function was created with. The onus is on the embedder to ensure that args_and_results are all read correctly for parameters and all written for results within the execution of a function.

Parameters will be listed starting at index 0 in the args_and_results array. Results are also written starting at index 0, which will overwrite the arguments.

Function Documentation

◆ wasmtime_caller_export_get()

bool wasmtime_caller_export_get ( wasmtime_caller_t caller,
const char *  name,
size_t  name_len,
wasmtime_extern_t item 
)

Loads a wasmtime_extern_t from the caller's context.

This function will attempt to look up the export named name on the caller instance provided. If it is found then the wasmtime_extern_t for that is returned, otherwise NULL is returned.

Note that this only works for exported memories right now for WASI compatibility.

Parameters
callerthe caller object to look up the export from
namethe name that's being looked up
name_lenthe byte length of name
itemwhere to store the return value

Returns a nonzero value if the export was found, or 0 if the export wasn't found. If the export wasn't found then item isn't written to.

◆ wasmtime_func_call()

wasmtime_error_t * wasmtime_func_call ( wasmtime_context_t store,
const wasmtime_func_t func,
const wasmtime_val_t args,
size_t  nargs,
wasmtime_val_t results,
size_t  nresults,
wasm_trap_t **  trap 
)

Call a WebAssembly function.

This function is used to invoke a function defined within a store. For example this might be used after extracting a function from a wasmtime_instance_t.

Parameters
storethe store which owns func
functhe function to call
argsthe arguments to the function call
nargsthe number of arguments provided
resultswhere to write the results of the function call
nresultsthe number of results expected
trapwhere to store a trap, if one happens.

There are three possible return states from this function:

  1. The returned error is non-null. This means results wasn't written to and trap will have NULL written to it. This state means that programmer error happened when calling the function, for example when the size of the arguments/results was wrong, the types of the arguments were wrong, or arguments may come from the wrong store.
  2. The trap pointer is filled in. This means the returned error is NULL and results was not written to. This state means that the function was executing but hit a wasm trap while executing.
  3. The error and trap returned are both NULL and results are written to. This means that the function call succeeded and the specified results were produced.

The trap pointer cannot be NULL. The args and results pointers may be NULL if the corresponding length is zero.

Does not take ownership of wasmtime_val_t arguments. Gives ownership of wasmtime_val_t results.

◆ wasmtime_func_call_unchecked()

wasm_trap_t * wasmtime_func_call_unchecked ( wasmtime_context_t store,
const wasmtime_func_t func,
wasmtime_val_raw_t args_and_results 
)

Call a WebAssembly function in an "unchecked" fashion.

This function is similar to wasmtime_func_call except that there is no type information provided with the arguments (or sizing information). Consequently this is less safe to call since it's up to the caller to ensure that args has an appropriate size and all the parameters are configured with their appropriate values/types. Additionally all the results must be interpreted correctly if this function returns successfully.

Parameters must be specified starting at index 0 in the args_and_results array. Results are written starting at index 0, which will overwrite the arguments.

Callers must ensure that various correctness variants are upheld when this API is called such as:

  • The args_and_results pointer has enough space to hold all the parameters and all the results (but not at the same time).
  • Parameters must all be configured as if they were the correct type.
  • Values such as externref and funcref are valid within the store being called.

When in doubt it's much safer to call wasmtime_func_call. This function is faster than that function, but the tradeoff is that embeddings must uphold more invariants rather than relying on Wasmtime to check them for you.

◆ wasmtime_func_from_raw()

void wasmtime_func_from_raw ( wasmtime_context_t context,
size_t  raw,
wasmtime_func_t ret 
)

Converts a raw nonzero funcref value from wasmtime_val_raw_t into a wasmtime_func_t.

This function can be used to interpret nonzero values of the funcref field of the wasmtime_val_raw_t structure. It is assumed that raw does not have a value of 0, or otherwise the program will abort.

Note that this function is unchecked and unsafe. It's only safe to pass values learned from wasmtime_val_raw_t with the same corresponding wasmtime_context_t that they were produced from. Providing arbitrary values to raw here or cross-context values with context is UB.

◆ wasmtime_func_new()

void wasmtime_func_new ( wasmtime_context_t store,
const wasm_functype_t type,
wasmtime_func_callback_t  callback,
void *  env,
void(*)(void *)  finalizer,
wasmtime_func_t ret 
)

Creates a new host-defined function.

Inserts a host-defined function into the store provided which can be used to then instantiate a module with or define within a wasmtime_linker_t.

Parameters
storethe store in which to create the function
typethe wasm type of the function that's being created
callbackthe host-defined callback to invoke
envhost-specific data passed to the callback invocation, can be NULL
finalizeroptional finalizer for env, can be NULL
retthe wasmtime_func_t return value to be filled in.

The returned function can only be used with the specified store.

◆ wasmtime_func_new_unchecked()

void wasmtime_func_new_unchecked ( wasmtime_context_t store,
const wasm_functype_t type,
wasmtime_func_unchecked_callback_t  callback,
void *  env,
void(*)(void *)  finalizer,
wasmtime_func_t ret 
)

Creates a new host function in the same manner of wasmtime_func_new, but the function-to-call has no type information available at runtime.

This function is very similar to wasmtime_func_new. The difference is that this version is "more unsafe" in that when the host callback is invoked there is no type information and no checks that the right types of values are produced. The onus is on the consumer of this API to ensure that all invariants are upheld such as:

  • The host callback reads parameters correctly and interprets their types correctly.
  • If a trap doesn't happen then all results are written to the results pointer. All results must have the correct type.
  • Types such as funcref cannot cross stores.
  • Types such as externref have valid reference counts.

It's generally only recommended to use this if your application can wrap this in a safe embedding. This should not be frequently used due to the number of invariants that must be upheld on the wasm<->host boundary. On the upside, though, this flavor of host function will be faster to call than those created by wasmtime_func_new (hence the reason for this function's existence).

◆ wasmtime_func_type()

wasm_functype_t * wasmtime_func_type ( const wasmtime_context_t store,
const wasmtime_func_t func 
)

Returns the type of the function specified.

The returned wasm_functype_t is owned by the caller.