Representation of a WebAssembly function. More...

#include <wasmtime.hh>

Public Member Functions
	Func (wasmtime_func_t func)
	Creates a new function from the raw underlying C API representation.

template<typename F , std::enable_if_t< std::is_invocable_r_v< Result< std::monostate, Trap >, F, Caller, Span< const Val >, Span< Val > >, bool > = true>
	Func (Store::Context cx, const FuncType &ty, F f)
	Creates a new host-defined function. More...

template<typename I >
TrapResult< std::vector< Val > >	call (Store::Context cx, const I &begin, const I &end) const
	Invoke a WebAssembly function. More...

TrapResult< std::vector< Val > >	call (Store::Context cx, const std::vector< Val > &params) const

TrapResult< std::vector< Val > >	call (Store::Context cx, const std::initializer_list< Val > &params) const

FuncType	type (Store::Context cx) const
	Returns the type of this function.

template<typename Params , typename Results , std::enable_if_t< WasmTypeList< Params >::valid, bool > = true, std::enable_if_t< WasmTypeList< Results >::valid, bool > = true>
Result< TypedFunc< Params, Results >, Trap >	typed (Store::Context cx) const
	Statically checks this function against the provided types. More...

const wasmtime_func_t &	raw_func () const
	Returns the raw underlying C API function this is using.

Static Public Member Functions
template<typename F , std::enable_if_t< WasmHostFunc< F >::Params::valid, bool > = true, std::enable_if_t< WasmHostFunc< F >::Results::valid, bool > = true>
static Func	wrap (Store::Context cx, F f)
	Creates a new host function from the provided callback `f`, inferring the WebAssembly function type from the host signature. More...

Detailed Description

Representation of a WebAssembly function.

This class represents a WebAssembly function, either created through instantiating a module or a host function.

Note that this type does not itself own any resources. It points to resources owned within a Store and the Store must be passed in as the first argument to the functions defined on Func. Note that if the wrong Store is passed in then the process will be aborted.

Examples: externref.cc, hello.cc, interrupt.cc, and linking.cc.

Constructor & Destructor Documentation

◆ Func()

template<typename F , std::enable_if_t< std::is_invocable_r_v< Result< std::monostate, Trap >, F, Caller, Span< const Val >, Span< Val > >, bool > = true>

wasmtime::Func::Func	(	Store::Context	cx,
		const FuncType &	ty,
		F	f
	)

inline

Creates a new host-defined function.

This constructor is used to create a host function within the store provided. This is how WebAssembly can call into the host and make use of external functionality.

‍Note: host functions created this way are more flexible but not as fast to call as those created by Func::wrap.

Parameters

cx	the store to create the function within
ty	the type of the function that will be created
f	the host callback to be executed when this function is called.

The parameter f is expected to be a lambda (or a lambda lookalike) which takes three parameters:

The first parameter is a Caller to get recursive access to the store and other caller state.
The second parameter is a Span<const Val> which is the list of parameters to the function. These parameters are guaranteed to be of the types specified by ty when constructing this function.
The last argument is Span<Val> which is where to write the return values of the function. The function must produce the types of values specified by ty or otherwise a trap will be raised.

The parameter f is expected to return Result<std::monostate, Trap>. This allows f to raise a trap if desired, or otherwise return no trap and finish successfully. If a trap is raised then the results pointer does not need to be written to.

Member Function Documentation

◆ call()

template<typename I >

TrapResult< std::vector< Val > > wasmtime::Func::call	(	Store::Context	cx,
		const I &	begin,
		const I &	end
	)		const

inline

Invoke a WebAssembly function.

This function will execute this WebAssembly function. This function muts be defined within the cx's store provided. The params argument is the list of parameters that are passed to the wasm function, and the types of the values within params must match the type signature of this function.

This may return one of three values:

First the function could succeed, returning a vector of values representing the results of the function.
Otherwise a Trap might be generated by the WebAssembly function.
Finally an Error could be returned indicating that params were not of the right type.

‍Note: for optimized calls into WebAssembly where the function signature is statically known it's recommended to use Func::typed and TypedFunc::call.

Examples: externref.cc, interrupt.cc, and linking.cc.

◆ typed()

template<typename Params , typename Results , std::enable_if_t< WasmTypeList< Params >::valid, bool > = true, std::enable_if_t< WasmTypeList< Results >::valid, bool > = true>

Result< TypedFunc< Params, Results >, Trap > wasmtime::Func::typed ( Store::Context cx ) const

inline

Statically checks this function against the provided types.

This function will check whether it takes the statically known Params and returns the statically known Results. If the type check succeeds then a TypedFunc is returned which enables a faster method of invoking WebAssembly functions.

The Params and Results specified as template parameters here are the parameters and results of the wasm function. They can either be a bare type which means that the wasm takes/returns one value, or they can be a std::tuple<T...> of types to represent multiple arguments or multiple returns.

The valid types for this function are those mentioned as the arguments for Func::wrap.

◆ wrap()

template<typename F , std::enable_if_t< WasmHostFunc< F >::Params::valid, bool > = true, std::enable_if_t< WasmHostFunc< F >::Results::valid, bool > = true>

static Func wasmtime::Func::wrap	(	Store::Context	cx,
		F	f
	)

inlinestatic

Creates a new host function from the provided callback f, inferring the WebAssembly function type from the host signature.

This function is akin to the Func constructor except that the WebAssembly type does not need to be specified and additionally the signature of f is different. The main goal of this function is to enable WebAssembly to call the function f as-fast-as-possible without having to validate any types or such.

The function f can optionally take a Caller as its first parameter, but otherwise its arguments are translated to WebAssembly types:

int32_t, uint32_t - i32
int64_t, uint64_t - i64
float - f32
double - f64
std::optional<Func> - funcref
std::optional<ExternRef> - externref
wasmtime::V128 - v128

The function may only take these arguments and if it takes any other kinds of arguments then it will fail to compile.

The function may return a few different flavors of return values:

void - interpreted as returning nothing
Any type above - interpreted as a singular return value.
std::tuple<T...> where T is one of the valid argument types - interpreted as returning multiple values.
Result<T, Trap> where T is another valid return type - interpreted as a function that returns T to wasm but is optionally allowed to also raise a trap.

It's recommended, if possible, to use this function over the Func constructor since this is generally easier to work with and also enables a faster path for WebAssembly to call this function.

The documentation for this class was generated from the following file:

include/wasmtime.hh

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Func()

Member Function Documentation

◆ call()

◆ typed()

◆ wrap()