/// \file wasmtime/component/val.h #ifndef WASMTIME_COMPONENT_VAL_H #define WASMTIME_COMPONENT_VAL_H #include #ifdef WASMTIME_FEATURE_COMPONENT_MODEL #include #include #include #include #ifdef __cplusplus extern "C" { #endif /// \brief 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. typedef struct wasmtime_component_resource_any wasmtime_component_resource_any_t; /// \brief 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`. WASM_API_EXTERN wasmtime_component_resource_type_t *wasmtime_component_resource_any_type( const wasmtime_component_resource_any_t *resource); /// \brief 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`. WASM_API_EXTERN wasmtime_component_resource_any_t *wasmtime_component_resource_any_clone( const wasmtime_component_resource_any_t *resource); /// \brief Returns whether this resource is an `own`, or a `borrow` in the /// component model. WASM_API_EXTERN bool wasmtime_component_resource_any_owned( const wasmtime_component_resource_any_t *resource); /// \brief 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`. WASM_API_EXTERN wasmtime_error_t *wasmtime_component_resource_any_drop( wasmtime_context_t *ctx, const wasmtime_component_resource_any_t *resource); /// \brief 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. WASM_API_EXTERN void wasmtime_component_resource_any_delete( wasmtime_component_resource_any_t *resource); /// \brief 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. typedef struct wasmtime_component_resource_host wasmtime_component_resource_host_t; /// \brief 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`. WASM_API_EXTERN wasmtime_component_resource_host_t * wasmtime_component_resource_host_new(bool owned, uint32_t rep, uint32_t ty); /// \brief 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`. WASM_API_EXTERN wasmtime_component_resource_host_t *wasmtime_component_resource_host_clone( const wasmtime_component_resource_host_t *resource); /// \brief 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. WASM_API_EXTERN uint32_t wasmtime_component_resource_host_rep( const wasmtime_component_resource_host_t *resource); /// \brief 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. WASM_API_EXTERN uint32_t wasmtime_component_resource_host_type( const wasmtime_component_resource_host_t *resource); /// \brief Returns whether this host-defined resource is an `own` or a `borrow` /// in the component model. WASM_API_EXTERN bool wasmtime_component_resource_host_owned( const wasmtime_component_resource_host_t *resource); /// \brief Deallocates a host-defined component resource. /// /// This function deallocates any host-side memory associated with this /// resource. WASM_API_EXTERN void wasmtime_component_resource_host_delete( wasmtime_component_resource_host_t *resource); /// \brief 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`. 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); /// \brief 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. 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); /// \brief Discriminant used in #wasmtime_component_val_t::kind typedef uint8_t wasmtime_component_valkind_t; /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a bool #define WASMTIME_COMPONENT_BOOL 0 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a s8 #define WASMTIME_COMPONENT_S8 1 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a u8 #define WASMTIME_COMPONENT_U8 2 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a s16 #define WASMTIME_COMPONENT_S16 3 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a u16 #define WASMTIME_COMPONENT_U16 4 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a s32 #define WASMTIME_COMPONENT_S32 5 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a u32 #define WASMTIME_COMPONENT_U32 6 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a s64 #define WASMTIME_COMPONENT_S64 7 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a u64 #define WASMTIME_COMPONENT_U64 8 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a f32 #define WASMTIME_COMPONENT_F32 9 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a f64 #define WASMTIME_COMPONENT_F64 10 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a char #define WASMTIME_COMPONENT_CHAR 11 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a string #define WASMTIME_COMPONENT_STRING 12 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a list #define WASMTIME_COMPONENT_LIST 13 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a record #define WASMTIME_COMPONENT_RECORD 14 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a tuple #define WASMTIME_COMPONENT_TUPLE 15 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a variant #define WASMTIME_COMPONENT_VARIANT 16 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a enum #define WASMTIME_COMPONENT_ENUM 17 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a option #define WASMTIME_COMPONENT_OPTION 18 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a result #define WASMTIME_COMPONENT_RESULT 19 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is flags #define WASMTIME_COMPONENT_FLAGS 20 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a resource #define WASMTIME_COMPONENT_RESOURCE 21 /// \brief Value of #wasmtime_component_valkind_t meaning that /// #wasmtime_component_val_t is a map #define WASMTIME_COMPONENT_MAP 22 struct wasmtime_component_val; struct wasmtime_component_valrecord_entry; struct wasmtime_component_valmap_entry; #define DECLARE_VEC(name, type) \ /** \brief A vec of a type */ \ typedef struct name { \ /** Length of the vec */ \ size_t size; \ /** Pointer to the elements */ \ type *data; \ } name##_t; \ \ /** \brief Create vec from \p ptr and \p size */ \ WASM_API_EXTERN void name##_new(name##_t *out, size_t size, \ const type *ptr); \ /** \brief Create an empty vec */ \ WASM_API_EXTERN void name##_new_empty(name##_t *out); \ /** \brief Create a vec with length \p size */ \ WASM_API_EXTERN void name##_new_uninit(name##_t *out, size_t size); \ /** \brief Copy \p src to \p dst */ \ WASM_API_EXTERN void name##_copy(name##_t *dst, const name##_t *src); \ /** \brief Delete \p value */ \ WASM_API_EXTERN void name##_delete(name##_t *value); DECLARE_VEC(wasmtime_component_vallist, struct wasmtime_component_val) DECLARE_VEC(wasmtime_component_valrecord, struct wasmtime_component_valrecord_entry) DECLARE_VEC(wasmtime_component_valtuple, struct wasmtime_component_val) DECLARE_VEC(wasmtime_component_valflags, wasm_name_t) DECLARE_VEC(wasmtime_component_valmap, struct wasmtime_component_valmap_entry) #undef DECLARE_VEC /// Represents a variant type typedef struct { /// The discriminant of the variant wasm_name_t discriminant; /// The payload of the variant struct wasmtime_component_val *val; } wasmtime_component_valvariant_t; /// Represents a result type typedef struct { /// The discriminant of the result bool is_ok; /// The 'ok' value if #wasmtime_component_valresult_t::is_ok is `true`, else /// the 'err' value struct wasmtime_component_val *val; } wasmtime_component_valresult_t; /// \brief Represents possible runtime values which a component function can /// either consume or produce typedef union { /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_BOOL bool boolean; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_S8 int8_t s8; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_U8 uint8_t u8; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_S16 int16_t s16; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_U16 uint16_t u16; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_S32 int32_t s32; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_U32 uint32_t u32; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_S64 int64_t s64; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_U64 uint64_t u64; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_F32 float32_t f32; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_F64 float64_t f64; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_CHAR uint32_t character; /// Field used if #wasmtime_component_val_t::kind is /// #WASMTIME_COMPONENT_STRING wasm_name_t string; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_LIST wasmtime_component_vallist_t list; /// Field used if #wasmtime_component_val_t::kind is /// #WASMTIME_COMPONENT_RECORD wasmtime_component_valrecord_t record; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_TUPLE wasmtime_component_valtuple_t tuple; /// Field used if #wasmtime_component_val_t::kind is /// #WASMTIME_COMPONENT_VARIANT wasmtime_component_valvariant_t variant; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_ENUM wasm_name_t enumeration; /// Field used if #wasmtime_component_val_t::kind is /// #WASMTIME_COMPONENT_OPTION struct wasmtime_component_val *option; /// Field used if #wasmtime_component_val_t::kind is /// #WASMTIME_COMPONENT_RESULT wasmtime_component_valresult_t result; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_FLAGS wasmtime_component_valflags_t flags; /// Field used if #wasmtime_component_val_t::kind is #WASMTIME_COMPONENT_MAP wasmtime_component_valmap_t map; /// Field used if #wasmtime_component_val_t::kind is /// #WASMTIME_COMPONENT_RESOURCE wasmtime_component_resource_any_t *resource; } wasmtime_component_valunion_t; /// \brief Represents possible runtime values which a component function can /// either consume or produce typedef struct wasmtime_component_val { /// The type discriminant wasmtime_component_valkind_t kind; /// Value of type \ref kind wasmtime_component_valunion_t of; } wasmtime_component_val_t; /// \brief A pair of a name and a value that represents one entry in a value /// with kind #WASMTIME_COMPONENT_RECORD typedef struct wasmtime_component_valrecord_entry { /// The name of this entry wasm_name_t name; /// The value of this entry wasmtime_component_val_t val; } wasmtime_component_valrecord_entry_t; /// \brief A pair of a key and a value that represents one entry in a value /// with kind #WASMTIME_COMPONENT_MAP typedef struct wasmtime_component_valmap_entry { /// The key of this entry wasmtime_component_val_t key; /// The value of this entry wasmtime_component_val_t value; } wasmtime_component_valmap_entry_t; /// \brief 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. WASM_API_EXTERN wasmtime_component_val_t * wasmtime_component_val_new(wasmtime_component_val_t *val); /// \brief 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`. WASM_API_EXTERN void wasmtime_component_val_free(wasmtime_component_val_t *ptr); /// \brief 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. WASM_API_EXTERN void wasmtime_component_val_clone(const wasmtime_component_val_t *src, wasmtime_component_val_t *dst); /// \brief 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. WASM_API_EXTERN void wasmtime_component_val_delete(wasmtime_component_val_t *value); #ifdef __cplusplus } // extern "C" #endif #endif // WASMTIME_FEATURE_COMPONENT_MODEL #endif // WASMTIME_COMPONENT_VAL_H