#include <wasmtime/val.h>

Data Structures
struct	wasmtime_eqref
	A WebAssembly `eqref` value. More...

struct	wasmtime_field_type
	Describes the type and mutability of a struct field or array element. More...

struct	wasmtime_structref
	A WebAssembly `structref` value. More...

Macros
#define	WASMTIME_STORAGE_KIND_I8 9
	An 8-bit packed integer (only valid inside struct/array fields).

#define	WASMTIME_STORAGE_KIND_I16 10
	A 16-bit packed integer (only valid inside struct/array fields).

Typedefs
typedef struct wasmtime_eqref	wasmtime_eqref_t
	Convenience alias for wasmtime_eqref.

typedef uint8_t	wasmtime_storage_kind_t
	Discriminant for storage types in struct/array field types. More...

typedef struct wasmtime_field_type	wasmtime_field_type_t
	Convenience alias for wasmtime_field_type.

typedef struct wasmtime_struct_type	wasmtime_struct_type_t
	An opaque handle to a WebAssembly struct type definition. More...

typedef struct wasmtime_struct_ref_pre	wasmtime_struct_ref_pre_t
	An opaque, pre-allocated, and registered struct layout for faster allocation. More...

typedef struct wasmtime_structref	wasmtime_structref_t
	Convenience alias for wasmtime_structref.

Functions
WASM_API_EXTERN void	wasmtime_eqref_clone (const wasmtime_eqref_t eqref, wasmtime_eqref_t out)
	Clone an `eqref`, creating a new root. More...

WASM_API_EXTERN void	wasmtime_eqref_unroot (wasmtime_eqref_t *ref)
	Unroot an `eqref` to allow garbage collection. More...

WASM_API_EXTERN void	wasmtime_eqref_to_anyref (const wasmtime_eqref_t eqref, wasmtime_anyref_t out)
	Upcast an `eqref` to an `anyref`. More...

WASM_API_EXTERN void	wasmtime_eqref_from_i31 (wasmtime_context_t context, uint32_t i31val, wasmtime_eqref_t out)
	Create a new `i31ref` value. More...

WASM_API_EXTERN bool	wasmtime_eqref_is_i31 (wasmtime_context_t context, const wasmtime_eqref_t eqref)
	Test whether this `eqref` is an `i31ref`. More...

WASM_API_EXTERN bool	wasmtime_eqref_i31_get_u (wasmtime_context_t context, const wasmtime_eqref_t eqref, uint32_t *dst)
	Get the `eqref`'s underlying `i31ref` value, zero extended. More...

WASM_API_EXTERN bool	wasmtime_eqref_i31_get_s (wasmtime_context_t context, const wasmtime_eqref_t eqref, int32_t *dst)
	Get the `eqref`'s underlying `i31ref` value, sign extended. More...

WASM_API_EXTERN wasmtime_struct_type_t *	wasmtime_struct_type_new (const wasm_engine_t engine, const wasmtime_field_type_t fields, size_t nfields)
	Create a new struct type. More...

WASM_API_EXTERN void	wasmtime_struct_type_delete (wasmtime_struct_type_t *ty)
	Delete a struct type.

WASM_API_EXTERN wasmtime_struct_ref_pre_t *	wasmtime_struct_ref_pre_new (wasmtime_context_t context, const wasmtime_struct_type_t ty)
	Create a new struct pre-allocator. More...

WASM_API_EXTERN void	wasmtime_struct_ref_pre_delete (wasmtime_struct_ref_pre_t *pre)
	Delete a struct pre-allocator.

WASM_API_EXTERN wasmtime_error_t *	wasmtime_structref_new (wasmtime_context_t context, const wasmtime_struct_ref_pre_t pre, const wasmtime_val_t fields, size_t nfields, wasmtime_structref_t out)
	Allocate a new struct instance. More...

WASM_API_EXTERN void	wasmtime_structref_clone (const wasmtime_structref_t structref, wasmtime_structref_t out)
	Clone a `structref`, creating a new root.

WASM_API_EXTERN void	wasmtime_structref_unroot (wasmtime_structref_t *ref)
	Unroot a `structref` to allow garbage collection.

WASM_API_EXTERN void	wasmtime_structref_to_anyref (const wasmtime_structref_t structref, wasmtime_anyref_t out)
	Upcast a `structref` to an `anyref`.

WASM_API_EXTERN void	wasmtime_structref_to_eqref (const wasmtime_structref_t structref, wasmtime_eqref_t out)
	Upcast a `structref` to an `eqref`.

WASM_API_EXTERN wasmtime_error_t *	wasmtime_structref_field (wasmtime_context_t context, const wasmtime_structref_t structref, size_t index, wasmtime_val_t *out)
	Read a field from a struct. More...

WASM_API_EXTERN wasmtime_error_t *	wasmtime_structref_set_field (wasmtime_context_t context, const wasmtime_structref_t structref, size_t index, const wasmtime_val_t *val)
	Set a field of a struct. More...

WASM_API_EXTERN bool	wasmtime_eqref_is_struct (wasmtime_context_t context, const wasmtime_eqref_t eqref)
	Test whether an `eqref` is a `structref`. More...

WASM_API_EXTERN bool	wasmtime_eqref_as_struct (wasmtime_context_t context, const wasmtime_eqref_t eqref, wasmtime_structref_t *out)
	Downcast an `eqref` to a `structref`. More...

Detailed Description

APIs for interacting with WebAssembly GC types in Wasmtime.

This header provides types and functions for GC reference types beyond the basic anyref and externref in val.h: eqref, structref, and arrayref.

Typedef Documentation

◆ wasmtime_storage_kind_t

typedef uint8_t wasmtime_storage_kind_t

Discriminant for storage types in struct/array field types.

Extends wasmtime_valkind_t with packed storage types WASMTIME_STORAGE_KIND_I8 and WASMTIME_STORAGE_KIND_I16.

◆ wasmtime_struct_ref_pre_t

typedef struct wasmtime_struct_ref_pre wasmtime_struct_ref_pre_t

An opaque, pre-allocated, and registered struct layout for faster allocation.

Created from a wasmtime_struct_type_t and a store context. Reusable for allocating many struct instances of the same type.

Owned. Must be deleted with wasmtime_struct_ref_pre_delete.

◆ wasmtime_struct_type_t

typedef struct wasmtime_struct_type wasmtime_struct_type_t

An opaque handle to a WebAssembly struct type definition.

A struct type describes the fields of a struct. It is used to create a wasmtime_struct_ref_pre_t, which can then allocate struct instances.

Owned. Must be deleted with wasmtime_struct_type_delete.

Function Documentation

◆ wasmtime_eqref_as_struct()

WASM_API_EXTERN bool wasmtime_eqref_as_struct	(	wasmtime_context_t *	context,
		const wasmtime_eqref_t *	eqref,
		wasmtime_structref_t *	out
	)

Downcast an eqref to a structref.

If the given eqref is a structref, a new root for it is stored in out and true is returned. Otherwise false is returned and out is set to null.

◆ wasmtime_eqref_clone()

WASM_API_EXTERN void wasmtime_eqref_clone	(	const wasmtime_eqref_t *	eqref,
		wasmtime_eqref_t *	out
	)

Clone an eqref, creating a new root.

The cloned reference is stored in out.

◆ wasmtime_eqref_from_i31()

WASM_API_EXTERN void wasmtime_eqref_from_i31	(	wasmtime_context_t *	context,
		uint32_t	i31val,
		wasmtime_eqref_t *	out
	)

Create a new i31ref value.

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

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

◆ wasmtime_eqref_i31_get_s()

WASM_API_EXTERN bool wasmtime_eqref_i31_get_s	(	wasmtime_context_t *	context,
		const wasmtime_eqref_t *	eqref,
		int32_t *	dst
	)

Get the eqref's underlying i31ref value, sign extended.

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

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

◆ wasmtime_eqref_i31_get_u()

WASM_API_EXTERN bool wasmtime_eqref_i31_get_u	(	wasmtime_context_t *	context,
		const wasmtime_eqref_t *	eqref,
		uint32_t *	dst
	)

Get the eqref's underlying i31ref value, zero extended.

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

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

◆ wasmtime_eqref_is_i31()

WASM_API_EXTERN bool wasmtime_eqref_is_i31	(	wasmtime_context_t *	context,
		const wasmtime_eqref_t *	eqref
	)

Test whether this eqref is an i31ref.

Returns true if the given eqref is an i31ref, false otherwise. Returns false for null references.

◆ wasmtime_eqref_is_struct()

WASM_API_EXTERN bool wasmtime_eqref_is_struct	(	wasmtime_context_t *	context,
		const wasmtime_eqref_t *	eqref
	)

Test whether an eqref is a structref.

Returns false for null references.

◆ wasmtime_eqref_to_anyref()

WASM_API_EXTERN void wasmtime_eqref_to_anyref	(	const wasmtime_eqref_t *	eqref,
		wasmtime_anyref_t *	out
	)

Upcast an eqref to an anyref.

The original eqref is not consumed; out receives a new cloned root pointing to the same GC object as anyref.

◆ wasmtime_eqref_unroot()

WASM_API_EXTERN void wasmtime_eqref_unroot ( wasmtime_eqref_t * ref )

Unroot an eqref to allow garbage collection.

After calling this, ref is left in an undefined state and should not be used again.

◆ wasmtime_struct_ref_pre_new()

WASM_API_EXTERN wasmtime_struct_ref_pre_t * wasmtime_struct_ref_pre_new	(	wasmtime_context_t *	context,
		const wasmtime_struct_type_t *	ty
	)

Create a new struct pre-allocator.

Parameters

context	The store context.
ty	The struct type.

Returns: Returns a new struct ref pre-allocator.

◆ wasmtime_struct_type_new()

WASM_API_EXTERN wasmtime_struct_type_t * wasmtime_struct_type_new	(	const wasm_engine_t *	engine,
		const wasmtime_field_type_t *	fields,
		size_t	nfields
	)

Create a new struct type.

Parameters

engine	The engine to register the type with.
fields	Pointer to an array of field type descriptors.
nfields	Number of fields.

Returns: Returns a new struct type, or NULL on error (e.g. invalid field types).

◆ wasmtime_structref_field()

WASM_API_EXTERN wasmtime_error_t * wasmtime_structref_field	(	wasmtime_context_t *	context,
		const wasmtime_structref_t *	structref,
		size_t	index,
		wasmtime_val_t *	out
	)

Read a field from a struct.

Parameters

context	The store context.
structref	The struct to read from (not consumed).
index	The field index.
out	Receives the field value on success.

Returns: NULL on success, or a wasmtime_error_t on failure.

◆ wasmtime_structref_new()

WASM_API_EXTERN wasmtime_error_t * wasmtime_structref_new	(	wasmtime_context_t *	context,
		const wasmtime_struct_ref_pre_t *	pre,
		const wasmtime_val_t *	fields,
		size_t	nfields,
		wasmtime_structref_t *	out
	)

Allocate a new struct instance.

Parameters

context	The store context.
pre	The struct pre-allocator.
fields	Pointer to array of field values (wasmtime_val_t).
nfields	Number of fields (must match the struct type).
out	Receives the new structref on success.

Returns: NULL on success, or a wasmtime_error_t on failure.

◆ wasmtime_structref_set_field()

WASM_API_EXTERN wasmtime_error_t * wasmtime_structref_set_field	(	wasmtime_context_t *	context,
		const wasmtime_structref_t *	structref,
		size_t	index,
		const wasmtime_val_t *	val
	)

Set a field of a struct.

Parameters

context	The store context.
structref	The struct to write to (not consumed).
index	The field index.
val	The value to write (not consumed; caller must still unroot if applicable).

Returns: NULL on success, or a wasmtime_error_t on failure.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ wasmtime_storage_kind_t

◆ wasmtime_struct_ref_pre_t

◆ wasmtime_struct_type_t

Function Documentation

◆ wasmtime_eqref_as_struct()

◆ wasmtime_eqref_clone()

◆ wasmtime_eqref_from_i31()

◆ wasmtime_eqref_i31_get_s()

◆ wasmtime_eqref_i31_get_u()

◆ wasmtime_eqref_is_i31()

◆ wasmtime_eqref_is_struct()

◆ wasmtime_eqref_to_anyref()

◆ wasmtime_eqref_unroot()

◆ wasmtime_struct_ref_pre_new()

◆ wasmtime_struct_type_new()

◆ wasmtime_structref_field()

◆ wasmtime_structref_new()

◆ wasmtime_structref_set_field()