component/val.h File Reference

#include <wasmtime/conf.h>
#include <stdint.h>
#include <wasm.h>
#include <wasmtime/component/types/resource.h>
#include <wasmtime/store.h>

Go to the source code of this file.

Data Structures
struct	wasmtime_component_vallist
	A vec of a struct wasmtime_component_val More...
struct	wasmtime_component_valrecord
	A vec of a struct wasmtime_component_valrecord_entry More...
struct	wasmtime_component_valtuple
	A vec of a struct wasmtime_component_val More...
struct	wasmtime_component_valflags
	A vec of a wasm_name_t More...
struct	wasmtime_component_valvariant_t
	Represents a variant type. More...
struct	wasmtime_component_valresult_t
	Represents a result type. More...
union	wasmtime_component_valunion_t
	Represents possible runtime values which a component function can either consume or produce. More...
struct	wasmtime_component_val
	Represents possible runtime values which a component function can either consume or produce. More...
struct	wasmtime_component_valrecord_entry
	A pair of a name and a value that represents one entry in a value with kind WASMTIME_COMPONENT_RECORD. More...

Macros
#define	WASMTIME_COMPONENT_BOOL   0
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a bool.
#define	WASMTIME_COMPONENT_S8   1
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a s8.
#define	WASMTIME_COMPONENT_U8   2
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a u8.
#define	WASMTIME_COMPONENT_S16   3
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a s16.
#define	WASMTIME_COMPONENT_U16   4
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a u16.
#define	WASMTIME_COMPONENT_S32   5
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a s32.
#define	WASMTIME_COMPONENT_U32   6
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a u32.
#define	WASMTIME_COMPONENT_S64   7
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a s64.
#define	WASMTIME_COMPONENT_U64   8
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a u64.
#define	WASMTIME_COMPONENT_F32   9
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a f32.
#define	WASMTIME_COMPONENT_F64   10
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a f64.
#define	WASMTIME_COMPONENT_CHAR   11
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a char.
#define	WASMTIME_COMPONENT_STRING   12
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a string.
#define	WASMTIME_COMPONENT_LIST   13
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a list.
#define	WASMTIME_COMPONENT_RECORD   14
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a record.
#define	WASMTIME_COMPONENT_TUPLE   15
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a tuple.
#define	WASMTIME_COMPONENT_VARIANT   16
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a variant.
#define	WASMTIME_COMPONENT_ENUM   17
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a enum.
#define	WASMTIME_COMPONENT_OPTION   18
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a option.
#define	WASMTIME_COMPONENT_RESULT   19
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a result.
#define	WASMTIME_COMPONENT_FLAGS   20
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is flags.
#define	WASMTIME_COMPONENT_RESOURCE   21
	Value of wasmtime_component_valkind_t meaning that wasmtime_component_val_t is a resource.

Typedefs
typedef struct wasmtime_component_resource_any	wasmtime_component_resource_any_t
	Represents a component resource which can be either guest-owned or host-owned. More...
typedef struct wasmtime_component_resource_host	wasmtime_component_resource_host_t
	Represents a host-defined component resource. More...
typedef uint8_t	wasmtime_component_valkind_t
	Discriminant used in wasmtime_component_val_t::kind.
typedef struct wasmtime_component_vallist	wasmtime_component_vallist_t
	A vec of a struct wasmtime_component_val
typedef struct wasmtime_component_valrecord	wasmtime_component_valrecord_t
	A vec of a struct wasmtime_component_valrecord_entry
typedef struct wasmtime_component_valtuple	wasmtime_component_valtuple_t
	A vec of a struct wasmtime_component_val
typedef struct wasmtime_component_valflags	wasmtime_component_valflags_t
	A vec of a wasm_name_t
typedef struct wasmtime_component_val	wasmtime_component_val_t
	Represents possible runtime values which a component function can either consume or produce.
typedef struct wasmtime_component_valrecord_entry	wasmtime_component_valrecord_entry_t
	A pair of a name and a value that represents one entry in a value with kind WASMTIME_COMPONENT_RECORD.

Functions
WASM_API_EXTERN wasmtime_component_resource_type_t *	wasmtime_component_resource_any_type (const wasmtime_component_resource_any_t *resource)
	Gets the type of a component resource. More...
WASM_API_EXTERN wasmtime_component_resource_any_t *	wasmtime_component_resource_any_clone (const wasmtime_component_resource_any_t *resource)
	Clones a component resource. More...
WASM_API_EXTERN bool	wasmtime_component_resource_any_owned (const wasmtime_component_resource_any_t *resource)
	Returns whether this resource is an own, or a borrow in the component model.
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_resource_any_drop (wasmtime_context_t *ctx, const wasmtime_component_resource_any_t *resource)
	Drops a component resource. More...
WASM_API_EXTERN void	wasmtime_component_resource_any_delete (wasmtime_component_resource_any_t *resource)
	Deallocates a component resource. More...
WASM_API_EXTERN wasmtime_component_resource_host_t *	wasmtime_component_resource_host_new (bool owned, uint32_t rep, uint32_t ty)
	Creates a new host-defined component resource. More...
WASM_API_EXTERN wasmtime_component_resource_host_t *	wasmtime_component_resource_host_clone (const wasmtime_component_resource_host_t *resource)
	Clones a host-defined component resource. More...
WASM_API_EXTERN uint32_t	wasmtime_component_resource_host_rep (const wasmtime_component_resource_host_t *resource)
	Gets the "rep" of a host-defined component resource. More...
WASM_API_EXTERN uint32_t	wasmtime_component_resource_host_type (const wasmtime_component_resource_host_t *resource)
	Gets the "type" of a host-defined component resource. More...
WASM_API_EXTERN bool	wasmtime_component_resource_host_owned (const wasmtime_component_resource_host_t *resource)
	Returns whether this host-defined resource is an own or a borrow in the component model.
WASM_API_EXTERN void	wasmtime_component_resource_host_delete (wasmtime_component_resource_host_t *resource)
	Deallocates a host-defined component resource. More...
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_resource_any_to_host (wasmtime_context_t *ctx, const wasmtime_component_resource_any_t *resource, wasmtime_component_resource_host_t **ret)
	Attempts to convert a wasmtime_component_resource_any_t into a wasmtime_component_resource_host_t. More...
WASM_API_EXTERN wasmtime_error_t *	wasmtime_component_resource_host_to_any (wasmtime_context_t *ctx, const wasmtime_component_resource_host_t *resource, wasmtime_component_resource_any_t **ret)
	Same as wasmtime_component_resource_any_to_host except for converting the other way around. More...
WASM_API_EXTERN void	wasmtime_component_vallist_new (wasmtime_component_vallist_t *out, size_t size, const struct wasmtime_component_val *ptr)
	Create vec from ptr and size.
WASM_API_EXTERN void	wasmtime_component_vallist_new_empty (wasmtime_component_vallist_t *out)
	Create an empty vec.
WASM_API_EXTERN void	wasmtime_component_vallist_new_uninit (wasmtime_component_vallist_t *out, size_t size)
	Create a vec with length size.
WASM_API_EXTERN void	wasmtime_component_vallist_copy (wasmtime_component_vallist_t *dst, const wasmtime_component_vallist_t *src)
	Copy src to dst.
WASM_API_EXTERN void	wasmtime_component_vallist_delete (wasmtime_component_vallist_t *value)
	Delete value.
WASM_API_EXTERN void	wasmtime_component_valrecord_new (wasmtime_component_valrecord_t *out, size_t size, const struct wasmtime_component_valrecord_entry *ptr)
	Create vec from ptr and size.
WASM_API_EXTERN void	wasmtime_component_valrecord_new_empty (wasmtime_component_valrecord_t *out)
	Create an empty vec.
WASM_API_EXTERN void	wasmtime_component_valrecord_new_uninit (wasmtime_component_valrecord_t *out, size_t size)
	Create a vec with length size.
WASM_API_EXTERN void	wasmtime_component_valrecord_copy (wasmtime_component_valrecord_t *dst, const wasmtime_component_valrecord_t *src)
	Copy src to dst.
WASM_API_EXTERN void	wasmtime_component_valrecord_delete (wasmtime_component_valrecord_t *value)
	Delete value.
WASM_API_EXTERN void	wasmtime_component_valtuple_new (wasmtime_component_valtuple_t *out, size_t size, const struct wasmtime_component_val *ptr)
	Create vec from ptr and size.
WASM_API_EXTERN void	wasmtime_component_valtuple_new_empty (wasmtime_component_valtuple_t *out)
	Create an empty vec.
WASM_API_EXTERN void	wasmtime_component_valtuple_new_uninit (wasmtime_component_valtuple_t *out, size_t size)
	Create a vec with length size.
WASM_API_EXTERN void	wasmtime_component_valtuple_copy (wasmtime_component_valtuple_t *dst, const wasmtime_component_valtuple_t *src)
	Copy src to dst.
WASM_API_EXTERN void	wasmtime_component_valtuple_delete (wasmtime_component_valtuple_t *value)
	Delete value.
WASM_API_EXTERN void	wasmtime_component_valflags_new (wasmtime_component_valflags_t *out, size_t size, const wasm_name_t *ptr)
	Create vec from ptr and size.
WASM_API_EXTERN void	wasmtime_component_valflags_new_empty (wasmtime_component_valflags_t *out)
	Create an empty vec.
WASM_API_EXTERN void	wasmtime_component_valflags_new_uninit (wasmtime_component_valflags_t *out, size_t size)
	Create a vec with length size.
WASM_API_EXTERN void	wasmtime_component_valflags_copy (wasmtime_component_valflags_t *dst, const wasmtime_component_valflags_t *src)
	Copy src to dst.
WASM_API_EXTERN void	wasmtime_component_valflags_delete (wasmtime_component_valflags_t *value)
	Delete value.
WASM_API_EXTERN wasmtime_component_val_t *	wasmtime_component_val_new (wasmtime_component_val_t *val)
	Allocates a new wasmtime_component_val_t on the heap, initializing it with the contents of val. More...
WASM_API_EXTERN void	wasmtime_component_val_free (wasmtime_component_val_t *ptr)
	Deallocates the heap-allocated value at ptr. More...
WASM_API_EXTERN void	wasmtime_component_val_clone (const wasmtime_component_val_t *src, wasmtime_component_val_t *dst)
	Performs a deep copy of the provided src, storing the results into dst. More...
WASM_API_EXTERN void	wasmtime_component_val_delete (wasmtime_component_val_t *value)
	Deallocates any memory owned by value. More...

Typedef Documentation

wasmtime_component_resource_any_t

typedef struct wasmtime_component_resource_any wasmtime_component_resource_any_t

Represents a component resource which can be either guest-owned or host-owned.

This type is an opaque type used to represent any component model resource. Internally this tracks information about ownership, type, etc. Values of this type have dynamic ownership guarantees associated with them. Notably from a component-model perspective values of this type must either be converted to a host resource with wasmtime_component_resource_any_to_host or dropped via wasmtime_component_resource_any_drop. This is required to handle various metadata tracking appropriately, and if this is not done then the resource will be leaked into the store and a trap may be raised.

Note that this type also has dynamic memory allocations associated with it and users must call wasmtime_component_resource_any_delete to deallocate the host-side resources. This destructor can be called in an RAII fashion and will only clean up memory, not metadata related to the resource. It is required to call wasmtime_component_resource_any_delete to prevent leaking memory on the host. It's highly recommended to call wasmtime_component_resource_any_drop to avoid leaking memory in a long-lived store, but if this is forgotten then deallocating the store will deallocate all memory still.

wasmtime_component_resource_host_t

typedef struct wasmtime_component_resource_host wasmtime_component_resource_host_t

Represents a host-defined component resource.

This structure is similar to wasmtime_component_resource_any_t except that it unconditionally represents an embedder-defined resource via this API. Host resources have a "rep" which is a 32-bit integer whose meaning is defined by the host. This "rep" is trusted in the sense that the guest cannot forge this so the embedder is the only one that can view this.

Host resources also have a 32-bit type whose meaning is also defined by the host and has no meaning internally. This is used to distinguish different types of resources from one another.

Also note that unlike wasmtime_component_resource_any_t host resources do not have a "drop" operation. It's up to the host to define what it means to drop an owned resource and handle that appropriately.

Function Documentation

wasmtime_component_resource_any_clone()

WASM_API_EXTERN wasmtime_component_resource_any_t * wasmtime_component_resource_any_clone

(

const wasmtime_component_resource_any_t *

resource

)

Clones a component resource.

Creates a new owned copy of a component resource. Note that the returned resource still logically refers to the same resource as before, but this can be convenient from an API perspective. Calls to wasmtime_component_resource_any_drop need only happen once-per-logical-resource, not once-per-handle-to-the-resource. Note though that calls to wasmtime_component_resource_any_delete must happen once-per-handle-to-the-resource.

The pointer returned from this function must be deallocated with wasmtime_component_resource_any_delete.

wasmtime_component_resource_any_delete()

WASM_API_EXTERN void wasmtime_component_resource_any_delete

(

wasmtime_component_resource_any_t *

resource

)

Deallocates a component resource.

This function deallocates any host-side memory associated with this resource. This function does not perform any component-model related cleanup, and wasmtime_component_resource_any_drop is required for that.

wasmtime_component_resource_any_drop()

WASM_API_EXTERN wasmtime_error_t * wasmtime_component_resource_any_drop	(	wasmtime_context_t *	ctx,
		const wasmtime_component_resource_any_t *	resource
	)

Drops a component resource.

This function is required to be called per "logical resource" to clean up any borrow-tracking state in the store, for example. Additionally this may invoke WebAssembly if it's a guest-owned resource with a destructor associated with it.

This operation is not to be confused with wasmtime_component_resource_any_delete which deallocates host-related memory for this resource. After wasmtime_component_resource_any_drop is called it's still required to call wasmtime_component_resource_any_delete.

wasmtime_component_resource_any_to_host()

WASM_API_EXTERN wasmtime_error_t * wasmtime_component_resource_any_to_host	(	wasmtime_context_t *	ctx,
		const wasmtime_component_resource_any_t *	resource,
		wasmtime_component_resource_host_t **	ret
	)

Attempts to convert a wasmtime_component_resource_any_t into a wasmtime_component_resource_host_t.

This function will attempt to convert the provided resource into a host-defined resource. If the resource is indeed host-defined then a new owned wasmtime_component_resource_host_t is returned via ret. If the resource is guest-defined then an error is returned and ret is not modified.

If no error is returned then the pointer written to ret must be deallocated with wasmtime_component_resource_host_delete.

wasmtime_component_resource_any_type()

WASM_API_EXTERN wasmtime_component_resource_type_t * wasmtime_component_resource_any_type

(

const wasmtime_component_resource_any_t *

resource

)

Gets the type of a component resource.

Returns an owned wasmtime_component_resource_type_t which represents the type of this resource.

The pointer returned from this function must be deallocated with wasmtime_component_resource_type_delete.

wasmtime_component_resource_host_clone()

WASM_API_EXTERN wasmtime_component_resource_host_t * wasmtime_component_resource_host_clone

(

const wasmtime_component_resource_host_t *

resource

)

Clones a host-defined component resource.

Creates a new owned copy of a host-defined component resource. Note that the returned resource still logically refers to the same resource as before, but this can be convenient from an API perspective.

The pointer returned from this function must be deallocated with wasmtime_component_resource_host_delete.

wasmtime_component_resource_host_delete()

WASM_API_EXTERN void wasmtime_component_resource_host_delete

(

wasmtime_component_resource_host_t *

resource

)

Deallocates a host-defined component resource.

This function deallocates any host-side memory associated with this resource.

wasmtime_component_resource_host_new()

WASM_API_EXTERN wasmtime_component_resource_host_t * wasmtime_component_resource_host_new	(	bool	owned,
		uint32_t	rep,
		uint32_t	ty
	)

Creates a new host-defined component resource.

This function creates a new host-defined component resource with the provided parameters. The owned parameter indicates whether this resource is an own or a borrow in the component model. The rep and ty parameters are 32-bit integers which only have meaning to the embedder and are plumbed through with this resource.

The pointer returned from this function must be deallocated with wasmtime_component_resource_host_delete.

wasmtime_component_resource_host_rep()

WASM_API_EXTERN uint32_t wasmtime_component_resource_host_rep

(

const wasmtime_component_resource_host_t *

resource

)

Gets the "rep" of a host-defined component resource.

Returns the 32-bit integer "rep" associated with this resource. This is a trusted value that guests cannot forge.

wasmtime_component_resource_host_to_any()

WASM_API_EXTERN wasmtime_error_t * wasmtime_component_resource_host_to_any	(	wasmtime_context_t *	ctx,
		const wasmtime_component_resource_host_t *	resource,
		wasmtime_component_resource_any_t **	ret
	)

Same as wasmtime_component_resource_any_to_host except for converting the other way around.

This can fail in some edge-case scenarios but typically does not fail.

wasmtime_component_resource_host_type()

WASM_API_EXTERN uint32_t wasmtime_component_resource_host_type

(

const wasmtime_component_resource_host_t *

resource

)

Gets the "type" of a host-defined component resource.

Returns the 32-bit integer "type" associated with this resource. This is a trusted value that guests cannot forge.

wasmtime_component_val_clone()

WASM_API_EXTERN void wasmtime_component_val_clone	(	const wasmtime_component_val_t *	src,
		wasmtime_component_val_t *	dst
	)

Performs a deep copy of the provided src, storing the results into dst.

The dst value must have wasmtime_component_val_delete run to discard its contents.

wasmtime_component_val_delete()

WASM_API_EXTERN void wasmtime_component_val_delete

(

wasmtime_component_val_t *

value

)

Deallocates any memory owned by value.

This function will look at value->kind and deallocate any memory if necessary. For example lists will deallocate value->of.list.

Note that this function is not to be confused with wasmtime_component_val_free which not only deallocates the memory that value owns but also deallocates the memory of value itself. This function should only be used when the embedder owns the pointer value itself.

wasmtime_component_val_free()

WASM_API_EXTERN void wasmtime_component_val_free

(

wasmtime_component_val_t *

ptr

)

Deallocates the heap-allocated value at ptr.

This function will perform wasmtime_component_val_delete on ptr and then it will deallocate ptr itself. This should not be used on embedder-owned ptr storage. This function is used to clean up allocations made by wasmtime_component_val_new.

wasmtime_component_val_new()

WASM_API_EXTERN wasmtime_component_val_t * wasmtime_component_val_new

(

wasmtime_component_val_t *

val

)

Allocates a new wasmtime_component_val_t on the heap, initializing it with the contents of val.

This function is intended to be used with the variant, result, and option fields of wasmtime_component_valunion_t. The returned pointer must be deallocated with wasmtime_component_val_free to deallocate the heap-owned pointer. The val provided is "taken" meaning that its contents are transferred to the returned pointer. This is not a clone operation but instead is an operation used to move val onto a Wasmtime-defined heap allocation.

Note that wasmtime_component_val_delete should not be used for deallocating the return value because that will deallocate the contents of the value but not the value pointer itself.