Add support for structref to the C and C++ APIs (#12915)

* Add support for `structref` to the C and C++ APIs

Also requires adding support for struct and field types, as well as
`StructRefPre`.

* review feedback and rebase

* fix doc build

* really fix doc build

* fix more docs

Author: fitzgen

crates/c-api/include/wasmtime/gc.h

@@ -126,6 +126,222 @@ WASM_API_EXTERN bool wasmtime_eqref_i31_get_s(wasmtime_context_t *context,
                                               const wasmtime_eqref_t *eqref,
                                               int32_t *dst);
 
+// ============================================================================
+// StructRef
+// ============================================================================
+
+/**
+ * \brief 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.
+ */
+typedef uint8_t wasmtime_storage_kind_t;
+
+/// \brief An 8-bit packed integer (only valid inside struct/array fields).
+#define WASMTIME_STORAGE_KIND_I8 9
+/// \brief A 16-bit packed integer (only valid inside struct/array fields).
+#define WASMTIME_STORAGE_KIND_I16 10
+
+/**
+ * \typedef wasmtime_field_type_t
+ * \brief Convenience alias for #wasmtime_field_type
+ *
+ * \struct wasmtime_field_type
+ * \brief Describes the type and mutability of a struct field or array element.
+ */
+typedef struct wasmtime_field_type {
+  /// The storage type of this field. Use #WASMTIME_I32, #WASMTIME_I64,
+  /// #WASMTIME_F32, etc. for value types, or #WASMTIME_STORAGE_KIND_I8 /
+  /// #WASMTIME_STORAGE_KIND_I16 for packed types.
+  wasmtime_storage_kind_t kind;
+  /// Whether this field is mutable. `true` for mutable, `false` for
+  /// immutable.
+  bool mutable_;
+} wasmtime_field_type_t;
+
+/**
+ * \brief 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.
+ */
+typedef struct wasmtime_struct_type wasmtime_struct_type_t;
+
+/**
+ * \brief Create a new struct type.
+ *
+ * \param engine The engine to register the type with.
+ * \param fields Pointer to an array of field type descriptors.
+ * \param nfields Number of fields.
+ *
+ * \return Returns a new struct type, or NULL on error (e.g. invalid field
+ * types).
+ */
+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);
+
+/**
+ * \brief Delete a struct type.
+ */
+WASM_API_EXTERN void wasmtime_struct_type_delete(wasmtime_struct_type_t *ty);
+
+/**
+ * \brief 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.
+ */
+typedef struct wasmtime_struct_ref_pre wasmtime_struct_ref_pre_t;
+
+/**
+ * \brief Create a new struct pre-allocator.
+ *
+ * \param context The store context.
+ * \param ty The struct type.
+ *
+ * \return Returns a new struct ref pre-allocator.
+ */
+WASM_API_EXTERN wasmtime_struct_ref_pre_t *
+wasmtime_struct_ref_pre_new(wasmtime_context_t *context,
+                            const wasmtime_struct_type_t *ty);
+
+/**
+ * \brief Delete a struct pre-allocator.
+ */
+WASM_API_EXTERN void
+wasmtime_struct_ref_pre_delete(wasmtime_struct_ref_pre_t *pre);
+
+/**
+ * \typedef wasmtime_structref_t
+ * \brief Convenience alias for #wasmtime_structref
+ *
+ * \struct wasmtime_structref
+ * \brief A WebAssembly `structref` value.
+ *
+ * This structure represents a reference to a GC struct. It is a subtype of
+ * `eqref` and `anyref`.
+ *
+ * Values must be explicitly unrooted via #wasmtime_structref_unroot.
+ */
+typedef struct wasmtime_structref {
+  /// Internal metadata.
+  uint64_t store_id;
+  /// Internal to Wasmtime.
+  uint32_t __private1;
+  /// Internal to Wasmtime.
+  uint32_t __private2;
+  /// Internal to Wasmtime.
+  void *__private3;
+} wasmtime_structref_t;
+
+/// \brief Initialize the `ref` to a null `structref` value.
+static inline void wasmtime_structref_set_null(wasmtime_structref_t *ref) {
+  ref->store_id = 0;
+}
+
+/// \brief Returns whether the provided `ref` is a null `structref` value.
+static inline bool wasmtime_structref_is_null(const wasmtime_structref_t *ref) {
+  return ref->store_id == 0;
+}
+
+/**
+ * \brief Allocate a new struct instance.
+ *
+ * \param context The store context.
+ * \param pre The struct pre-allocator.
+ * \param fields Pointer to array of field values (#wasmtime_val_t).
+ * \param nfields Number of fields (must match the struct type).
+ * \param out Receives the new structref on success.
+ *
+ * \return NULL on success, or a #wasmtime_error_t on failure.
+ */
+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);
+
+/**
+ * \brief Clone a `structref`, creating a new root.
+ */
+WASM_API_EXTERN void
+wasmtime_structref_clone(const wasmtime_structref_t *structref,
+                         wasmtime_structref_t *out);
+
+/**
+ * \brief Unroot a `structref` to allow garbage collection.
+ */
+WASM_API_EXTERN void wasmtime_structref_unroot(wasmtime_structref_t *ref);
+
+/**
+ * \brief Upcast a `structref` to an `anyref`.
+ */
+WASM_API_EXTERN void
+wasmtime_structref_to_anyref(const wasmtime_structref_t *structref,
+                             wasmtime_anyref_t *out);
+
+/**
+ * \brief Upcast a `structref` to an `eqref`.
+ */
+WASM_API_EXTERN void
+wasmtime_structref_to_eqref(const wasmtime_structref_t *structref,
+                            wasmtime_eqref_t *out);
+
+/**
+ * \brief Read a field from a struct.
+ *
+ * \param context The store context.
+ * \param structref The struct to read from (not consumed).
+ * \param index The field index.
+ * \param out Receives the field value on success.
+ *
+ * \return NULL on success, or a #wasmtime_error_t on failure.
+ */
+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);
+
+/**
+ * \brief Set a field of a struct.
+ *
+ * \param context The store context.
+ * \param structref The struct to write to (not consumed).
+ * \param index The field index.
+ * \param val The value to write (not consumed; caller must still unroot if
+ *        applicable).
+ *
+ * \return NULL on success, or a #wasmtime_error_t on failure.
+ */
+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);
+
+/**
+ * \brief Test whether an `eqref` is a `structref`.
+ *
+ * Returns `false` for null references.
+ */
+WASM_API_EXTERN bool wasmtime_eqref_is_struct(wasmtime_context_t *context,
+                                              const wasmtime_eqref_t *eqref);
+
+/**
+ * \brief 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.
+ */
+WASM_API_EXTERN bool wasmtime_eqref_as_struct(wasmtime_context_t *context,
+                                              const wasmtime_eqref_t *eqref,
+                                              wasmtime_structref_t *out);
+
 #ifdef __cplusplus
 } // extern "C"
 #endif