Add eqref support to the C and C++ APIs (#12914)

* Add `eqref` support to the C and C++ APIs

* fix doc build

Author: fitzgen

crates/c-api/include/wasmtime.h

@@ -205,6 +205,7 @@
 #include <wasmtime/tag.h>
 #include <wasmtime/trap.h>
 #include <wasmtime/val.h>
+#include <wasmtime/gc.h>
 #include <wasmtime/async.h>
 #include <wasmtime/component.h>
 #include <wasmtime/wat.h>

crates/c-api/include/wasmtime.hh

@@ -41,6 +41,7 @@
 #include <wasmtime/exn.hh>
 #include <wasmtime/extern.hh>
 #include <wasmtime/func.hh>
+#include <wasmtime/gc.hh>
 #include <wasmtime/global.hh>
 #include <wasmtime/instance.hh>
 #include <wasmtime/linker.hh>

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

@@ -0,0 +1,133 @@
+/**
+ * \file wasmtime/gc.h
+ *
+ * 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`.
+ */
+
+#ifndef WASMTIME_GC_H
+#define WASMTIME_GC_H
+
+#include <wasmtime/val.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * \typedef wasmtime_eqref_t
+ * \brief Convenience alias for #wasmtime_eqref
+ *
+ * \struct wasmtime_eqref
+ * \brief A WebAssembly `eqref` value.
+ *
+ * This structure represents a reference to a GC object that can be tested for
+ * equality. The subtypes of `eqref` include `structref`, `arrayref`, and
+ * `i31ref`.
+ *
+ * This type has the same representation and ownership semantics as
+ * #wasmtime_anyref_t. Values must be explicitly unrooted via
+ * #wasmtime_eqref_unroot to enable garbage collection.
+ */
+typedef struct wasmtime_eqref {
+  /// Internal metadata tracking within the store, embedders should not
+  /// configure or modify these fields.
+  uint64_t store_id;
+  /// Internal to Wasmtime.
+  uint32_t __private1;
+  /// Internal to Wasmtime.
+  uint32_t __private2;
+  /// Internal to Wasmtime.
+  void *__private3;
+} wasmtime_eqref_t;
+
+/// \brief Initialize the `ref` to a null `eqref` value.
+static inline void wasmtime_eqref_set_null(wasmtime_eqref_t *ref) {
+  ref->store_id = 0;
+}
+
+/// \brief Returns whether the provided `ref` is a null `eqref` value.
+static inline bool wasmtime_eqref_is_null(const wasmtime_eqref_t *ref) {
+  return ref->store_id == 0;
+}
+
+/**
+ * \brief Clone an `eqref`, creating a new root.
+ *
+ * The cloned reference is stored in `out`.
+ */
+WASM_API_EXTERN void wasmtime_eqref_clone(const wasmtime_eqref_t *eqref,
+                                          wasmtime_eqref_t *out);
+
+/**
+ * \brief Unroot an `eqref` to allow garbage collection.
+ *
+ * After calling this, `ref` is left in an undefined state and should not be
+ * used again.
+ */
+WASM_API_EXTERN void wasmtime_eqref_unroot(wasmtime_eqref_t *ref);
+
+/**
+ * \brief 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`.
+ */
+WASM_API_EXTERN void wasmtime_eqref_to_anyref(const wasmtime_eqref_t *eqref,
+                                              wasmtime_anyref_t *out);
+
+/**
+ * \brief 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.
+ */
+WASM_API_EXTERN void wasmtime_eqref_from_i31(wasmtime_context_t *context,
+                                             uint32_t i31val,
+                                             wasmtime_eqref_t *out);
+
+/**
+ * \brief Test whether this `eqref` is an `i31ref`.
+ *
+ * Returns `true` if the given `eqref` is an `i31ref`, `false` otherwise.
+ * Returns `false` for null references.
+ */
+WASM_API_EXTERN bool wasmtime_eqref_is_i31(wasmtime_context_t *context,
+                                           const wasmtime_eqref_t *eqref);
+
+/**
+ * \brief 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.
+ */
+WASM_API_EXTERN bool wasmtime_eqref_i31_get_u(wasmtime_context_t *context,
+                                              const wasmtime_eqref_t *eqref,
+                                              uint32_t *dst);
+
+/**
+ * \brief 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.
+ */
+WASM_API_EXTERN bool wasmtime_eqref_i31_get_s(wasmtime_context_t *context,
+                                              const wasmtime_eqref_t *eqref,
+                                              int32_t *dst);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // WASMTIME_GC_H

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

@@ -0,0 +1,100 @@
+/**
+ * \file wasmtime/gc.hh
+ *
+ * C++ API for WebAssembly GC types: eqref, structref, and arrayref.
+ */
+
+#ifndef WASMTIME_GC_HH
+#define WASMTIME_GC_HH
+
+#include <wasmtime/gc.h>
+#include <wasmtime/val.hh>
+
+namespace wasmtime {
+
+/**
+ * \brief Representation of a WebAssembly `eqref` value.
+ *
+ * An `eqref` is a reference to a GC object that supports equality testing.
+ * Subtypes include `structref`, `arrayref`, and `i31ref`.
+ *
+ * Like all GC references, `EqRef` values are rooted in a `Store` and must be
+ * unrooted (by destruction or move) to allow garbage collection.
+ */
+class EqRef {
+  friend class Val;
+  friend class AnyRef;
+
+  wasmtime_eqref_t val;
+
+public:
+  /// Creates a new `EqRef` from its C-API representation.
+  explicit EqRef(wasmtime_eqref_t val) : val(val) {}
+
+  /// Copy constructor.
+  EqRef(const EqRef &other) { wasmtime_eqref_clone(&other.val, &val); }
+
+  /// Copy assignment.
+  EqRef &operator=(const EqRef &other) {
+    wasmtime_eqref_unroot(&val);
+    wasmtime_eqref_clone(&other.val, &val);
+    return *this;
+  }
+
+  /// Move constructor.
+  EqRef(EqRef &&other) {
+    val = other.val;
+    wasmtime_eqref_set_null(&other.val);
+  }
+
+  /// Move assignment.
+  EqRef &operator=(EqRef &&other) {
+    wasmtime_eqref_unroot(&val);
+    val = other.val;
+    wasmtime_eqref_set_null(&other.val);
+    return *this;
+  }
+
+  ~EqRef() { wasmtime_eqref_unroot(&val); }
+
+  /// Create an `eqref` from an i31 value.
+  static EqRef from_i31(Store::Context cx, uint32_t val) {
+    wasmtime_eqref_t out;
+    wasmtime_eqref_from_i31(cx.capi(), val, &out);
+    return EqRef(out);
+  }
+
+  /// Returns `true` if this eqref is an i31ref.
+  bool is_i31(Store::Context cx) const {
+    return wasmtime_eqref_is_i31(cx.capi(), &val);
+  }
+
+  /// Get the i31 value as an unsigned 32-bit integer.
+  /// Returns `std::nullopt` if this eqref is not an i31ref.
+  std::optional<uint32_t> i31_get_u(Store::Context cx) const {
+    uint32_t dst;
+    if (wasmtime_eqref_i31_get_u(cx.capi(), &val, &dst))
+      return dst;
+    return std::nullopt;
+  }
+
+  /// Get the i31 value as a signed 32-bit integer.
+  /// Returns `std::nullopt` if this eqref is not an i31ref.
+  std::optional<int32_t> i31_get_s(Store::Context cx) const {
+    int32_t dst;
+    if (wasmtime_eqref_i31_get_s(cx.capi(), &val, &dst))
+      return dst;
+    return std::nullopt;
+  }
+
+  /// Upcast this `eqref` to an `anyref`.
+  AnyRef to_anyref() const {
+    wasmtime_anyref_t out;
+    wasmtime_eqref_to_anyref(&val, &out);
+    return AnyRef(out);
+  }
+};
+
+} // namespace wasmtime
+
+#endif // WASMTIME_GC_HH

crates/c-api/include/wasmtime/store.hh

@@ -75,6 +75,7 @@ public:
     friend class Linker;
     friend class ExternRef;
     friend class AnyRef;
+    friend class EqRef;
     friend class Val;
     friend class Store;
     friend class Tag;

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

@@ -15,6 +15,10 @@
 extern "C" {
 #endif
 
+struct wasmtime_eqref;
+/// Convenience alias for #wasmtime_eqref
+typedef struct wasmtime_eqref wasmtime_eqref_t;
+
 /**
  * \typedef wasmtime_anyref_t
  * \brief Convenience alias for #wasmtime_anyref
@@ -77,6 +81,19 @@ static inline bool wasmtime_anyref_is_null(const wasmtime_anyref_t *ref) {
 WASM_API_EXTERN void wasmtime_anyref_clone(const wasmtime_anyref_t *anyref,
                                            wasmtime_anyref_t *out);
 
+/**
+ * \brief Downcast an `anyref` to an `eqyref`.
+ *
+ * Returns `true` if the downcast succeeded, and `out` is initialized. Returns
+ * `false` if the downcast failed, and `out` is left uninitialized.
+ *
+ * The original `anyref` is not consumed; `out` receives a new cloned root
+ * pointing to the same GC object as `anyref`.
+ */
+WASM_API_EXTERN bool wasmtime_anyref_to_eqref(wasmtime_context_t *context,
+                                              const wasmtime_anyref_t *anyref,
+                                              wasmtime_eqref_t *out);
+
 /**
  * \brief Unroots the `ref` provided within the `context`.
  *
@@ -128,6 +145,15 @@ WASM_API_EXTERN void wasmtime_anyref_from_i31(wasmtime_context_t *context,
                                               uint32_t i31val,
                                               wasmtime_anyref_t *out);
 
+/**
+ * \brief Test whether an `anyref` is an `i31ref`.
+ *
+ * Returns `true` if the given `anyref` is an `i31ref`, `false` otherwise.
+ * Returns `false` for null references.
+ */
+WASM_API_EXTERN bool wasmtime_anyref_is_i31(wasmtime_context_t *context,
+                                            const wasmtime_anyref_t *anyref);
+
 /**
  * \brief Get the `anyref`'s underlying `i31ref` value, zero extended, if any.
  *

crates/c-api/include/wasmtime/val.hh

@@ -6,6 +6,7 @@
 #define WASMTIME_VAL_HH
 
 #include <optional>
+#include <wasmtime/gc.h>
 #include <wasmtime/store.hh>
 #include <wasmtime/types/val.hh>
 #include <wasmtime/val.h>
@@ -99,6 +100,8 @@ public:
   }
 };
 
+class EqRef;
+
 /**
  * \brief Representation of a WebAssembly `anyref` value.
  */
@@ -173,6 +176,11 @@ public:
       return ret;
     return std::nullopt;
   }
+
+  /// \brief Returns `true` if this anyref is an i31ref.
+  bool is_i31(Store::Context cx) const {
+    return wasmtime_anyref_is_i31(cx.ptr, &val);
+  }
 };
 
 /// \brief Container for the `v128` WebAssembly type.