val.h File Reference

#include <stdalign.h>
#include <wasm.h>
#include <wasmtime/extern.h>

Go to the source code of this file.

Data Structures
struct	wasmtime_anyref
	A WebAssembly value in the any hierarchy of GC types. More...
struct	wasmtime_externref
	A host-defined un-forgeable reference to pass into WebAssembly. More...
union	wasmtime_valunion
	Container for different kinds of wasm values. More...
union	wasmtime_val_raw
	Container for possible wasm values. More...
union	wasmtime_val
	Container for different kinds of wasm values. More...

Macros
#define	WASMTIME_I32   0
	Value of wasmtime_valkind_t meaning that wasmtime_val_t is an i32.
#define	WASMTIME_I64   1
	Value of wasmtime_valkind_t meaning that wasmtime_val_t is an i64.
#define	WASMTIME_F32   2
	Value of wasmtime_valkind_t meaning that wasmtime_val_t is a f32.
#define	WASMTIME_F64   3
	Value of wasmtime_valkind_t meaning that wasmtime_val_t is a f64.
#define	WASMTIME_V128   4
	Value of wasmtime_valkind_t meaning that wasmtime_val_t is a v128.
#define	WASMTIME_FUNCREF   5
	Value of wasmtime_valkind_t meaning that wasmtime_val_t is a funcref.
#define	WASMTIME_EXTERNREF   6
	Value of wasmtime_valkind_t meaning that wasmtime_val_t is an externref.
#define	WASMTIME_ANYREF   7
	Value of wasmtime_valkind_t meaning that wasmtime_val_t is an anyref.

Typedefs
typedef struct wasmtime_anyref	wasmtime_anyref_t
	Convenience alias for wasmtime_anyref.
typedef struct wasmtime_externref	wasmtime_externref_t
	Convenience alias for wasmtime_externref.
typedef uint8_t	wasmtime_valkind_t
	Discriminant stored in wasmtime_val::kind.
typedef uint8_t	wasmtime_v128[16]
	A 128-bit value representing the WebAssembly v128 type. Bytes are stored in little-endian order.
typedef union wasmtime_valunion	wasmtime_valunion_t
	Convenience alias for wasmtime_valunion.
typedef union wasmtime_val_raw	wasmtime_val_raw_t
	Convenience alias for wasmtime_val_raw.
typedef struct wasmtime_val	wasmtime_val_t
	Convenience alias for wasmtime_val_t.

Functions
void	wasmtime_anyref_clone (wasmtime_context_t *context, const wasmtime_anyref_t *anyref, wasmtime_anyref_t *out)
	Creates a new reference pointing to the same data that anyref points to (depending on the configured collector this might increase a reference count or create a new GC root). More...
void	wasmtime_anyref_unroot (wasmtime_context_t *context, wasmtime_anyref_t *ref)
	Unroots the ref provided within the context. More...
void	wasmtime_anyref_from_raw (wasmtime_context_t *context, uint32_t raw, wasmtime_anyref_t *out)
	Converts a raw anyref value coming from wasmtime_val_raw_t into a wasmtime_anyref_t. More...
uint32_t	wasmtime_anyref_to_raw (wasmtime_context_t *context, const wasmtime_anyref_t *ref)
	Converts a wasmtime_anyref_t to a raw value suitable for storing into a wasmtime_val_raw_t. More...
void	wasmtime_anyref_from_i31 (wasmtime_context_t *context, uint32_t i31val, wasmtime_anyref_t *out)
	Create a new i31ref value. More...
bool	wasmtime_anyref_i31_get_u (wasmtime_context_t *context, const wasmtime_anyref_t *anyref, uint32_t *dst)
	Get the anyref's underlying i31ref value, zero extended, if any. More...
bool	wasmtime_anyref_i31_get_s (wasmtime_context_t *context, const wasmtime_anyref_t *anyref, int32_t *dst)
	Get the anyref's underlying i31ref value, sign extended, if any. More...
bool	wasmtime_externref_new (wasmtime_context_t *context, void *data, void(*finalizer)(void *), wasmtime_externref_t *out)
	Create a new externref value. More...
void *	wasmtime_externref_data (wasmtime_context_t *context, const wasmtime_externref_t *data)
	Get an externref's wrapped data. More...
void	wasmtime_externref_clone (wasmtime_context_t *context, const wasmtime_externref_t *ref, wasmtime_externref_t *out)
	Creates a new reference pointing to the same data that ref points to (depending on the configured collector this might increase a reference count or create a new GC root). More...
void	wasmtime_externref_unroot (wasmtime_context_t *context, wasmtime_externref_t *ref)
	Unroots the pointer ref from the context provided. More...
void	wasmtime_externref_from_raw (wasmtime_context_t *context, uint32_t raw, wasmtime_externref_t *out)
	Converts a raw externref value coming from wasmtime_val_raw_t into a wasmtime_externref_t. More...
uint32_t	wasmtime_externref_to_raw (wasmtime_context_t *context, const wasmtime_externref_t *ref)
	Converts a wasmtime_externref_t to a raw value suitable for storing into a wasmtime_val_raw_t. More...
void	wasmtime_val_unroot (wasmtime_context_t *context, wasmtime_val_t *val)
	Unroot the value contained by val. More...
void	wasmtime_val_clone (wasmtime_context_t *context, const wasmtime_val_t *src, wasmtime_val_t *dst)
	Clones the value pointed to by src into the dst provided. More...

Detailed Description

APIs for interacting with WebAssembly values in Wasmtime.

Function Documentation

wasmtime_anyref_clone()

void wasmtime_anyref_clone	(	wasmtime_context_t *	context,
		const wasmtime_anyref_t *	anyref,
		wasmtime_anyref_t *	out
	)

Creates a new reference pointing to the same data that anyref points to (depending on the configured collector this might increase a reference count or create a new GC root).

The returned reference is stored in out.

wasmtime_anyref_from_i31()

void wasmtime_anyref_from_i31	(	wasmtime_context_t *	context,
		uint32_t	i31val,
		wasmtime_anyref_t *	out
	)

Create a new i31ref value.

Creates a new i31ref value (which is a subtype of anyref) and returns a pointer to it.

If i31val does not fit in 31 bits, it is wrapped.

wasmtime_anyref_from_raw()

void wasmtime_anyref_from_raw	(	wasmtime_context_t *	context,
		uint32_t	raw,
		wasmtime_anyref_t *	out
	)

Converts a raw anyref value coming from wasmtime_val_raw_t into a wasmtime_anyref_t.

The provided out pointer is filled in with a reference converted from raw.

wasmtime_anyref_i31_get_s()

bool wasmtime_anyref_i31_get_s	(	wasmtime_context_t *	context,
		const wasmtime_anyref_t *	anyref,
		int32_t *	dst
	)

Get the anyref's underlying i31ref value, sign extended, if any.

If the given anyref is an instance of i31ref, then its value is sign extended to 32 bits, written to dst, and true is returned.

If the given anyref is not an instance of i31ref, then false is returned and dst is left unmodified.

wasmtime_anyref_i31_get_u()

bool wasmtime_anyref_i31_get_u	(	wasmtime_context_t *	context,
		const wasmtime_anyref_t *	anyref,
		uint32_t *	dst
	)

Get the anyref's underlying i31ref value, zero extended, if any.

If the given anyref is an instance of i31ref, then its value is zero extended to 32 bits, written to dst, and true is returned.

If the given anyref is not an instance of i31ref, then false is returned and dst is left unmodified.

wasmtime_anyref_to_raw()

uint32_t wasmtime_anyref_to_raw	(	wasmtime_context_t *	context,
		const wasmtime_anyref_t *	ref
	)

Converts a wasmtime_anyref_t to a raw value suitable for storing into a wasmtime_val_raw_t.

Note that the returned underlying value is not tracked by Wasmtime's garbage collector until it enters WebAssembly. This means that a GC may release the context's reference to the raw value, making the raw value invalid within the context of the store. Do not perform a GC between calling this function and passing it to WebAssembly.

wasmtime_anyref_unroot()

void wasmtime_anyref_unroot	(	wasmtime_context_t *	context,
		wasmtime_anyref_t *	ref
	)

Unroots the ref provided within the context.

This API is required to enable the ref value provided to be garbage-collected. This API itself does not necessarily garbage-collect the value, but it's possible to collect it in the future after this.

This may modify ref and the contents of ref are left in an undefined state after this API is called and it should no longer be used.

Note that null or i32 anyref values do not need to be unrooted but are still valid to pass to this function.

wasmtime_externref_clone()

void wasmtime_externref_clone	(	wasmtime_context_t *	context,
		const wasmtime_externref_t *	ref,
		wasmtime_externref_t *	out
	)

Creates a new reference pointing to the same data that ref points to (depending on the configured collector this might increase a reference count or create a new GC root).

The out parameter stores the cloned reference. This reference must eventually be unrooted with wasmtime_externref_unroot in the future to enable GC'ing it.

wasmtime_externref_data()

void * wasmtime_externref_data	(	wasmtime_context_t *	context,
		const wasmtime_externref_t *	data
	)

Get an externref's wrapped data.

Returns the original data passed to wasmtime_externref_new. It is required that data is not NULL.

wasmtime_externref_from_raw()

void wasmtime_externref_from_raw	(	wasmtime_context_t *	context,
		uint32_t	raw,
		wasmtime_externref_t *	out
	)

Converts a raw externref value coming from wasmtime_val_raw_t into a wasmtime_externref_t.

The out reference is filled in with the non-raw version of this externref. It must eventually be unrooted with wasmtime_externref_unroot.

wasmtime_externref_new()

bool wasmtime_externref_new	(	wasmtime_context_t *	context,
		void *	data,
		void(*)(void *)	finalizer,
		wasmtime_externref_t *	out
	)

Create a new externref value.

Creates a new externref value wrapping the provided data, returning whether it was created or not.

Parameters

context	the store context to allocate this externref within
data	the host-specific data to wrap
finalizer	an optional finalizer for data
out	where to store the created value.

When the reference is reclaimed, the wrapped data is cleaned up with the provided finalizer.

If true is returned then out has been filled in and must be unrooted in the future with wasmtime_externref_unroot. If false is returned then the host wasn't able to create more GC values at this time. Performing a GC may free up enough space to try again.

wasmtime_externref_to_raw()

uint32_t wasmtime_externref_to_raw	(	wasmtime_context_t *	context,
		const wasmtime_externref_t *	ref
	)

Converts a wasmtime_externref_t to a raw value suitable for storing into a wasmtime_val_raw_t.

Note that the returned underlying value is not tracked by Wasmtime's garbage collector until it enters WebAssembly. This means that a GC may release the context's reference to the raw value, making the raw value invalid within the context of the store. Do not perform a GC between calling this function and passing it to WebAssembly.

wasmtime_externref_unroot()

void wasmtime_externref_unroot	(	wasmtime_context_t *	context,
		wasmtime_externref_t *	ref
	)

Unroots the pointer ref from the context provided.

This function will enable future garbage collection of the value pointed to by ref once there are no more references. The ref value may be mutated in place by this function and its contents are undefined after this function returns. It should not be used until after re-initializing it.

Note that null externref values do not need to be unrooted but are still valid to pass to this function.

wasmtime_val_clone()

void wasmtime_val_clone	(	wasmtime_context_t *	context,
		const wasmtime_val_t *	src,
		wasmtime_val_t *	dst
	)

Clones the value pointed to by src into the dst provided.

This function will clone any rooted GC values in src and have them newly rooted inside of dst. When using this API the dst should be later unrooted with wasmtime_val_unroot if it contains GC values.

wasmtime_val_unroot()

void wasmtime_val_unroot	(	wasmtime_context_t *	context,
		wasmtime_val_t *	val
	)

Unroot the value contained by val.

This function will unroot any GC references that val points to, for example if it has the WASMTIME_EXTERNREF or WASMTIME_ANYREF kinds. This function leaves val in an undefined state and it should not be used again without re-initializing.

This method does not need to be called for integers, floats, v128, or funcref values.