Support resources in the C API of Wasmtime (#11920)

This commit builds on #11885 to build out support for resources in
components in the C API of Wasmtime. Support is effectively the same as
in Rust except more things are behind pointers and `ResourceDynamic` is
used under the hood instead of `Resource<T>` due to the lack of
monomorphization. Tests have been updated to go through some various
situations of ensuring that guest and host resources are representable
and can be manipulated.

Author: alexcrichton

crates/c-api/include/wasmtime/component/linker.h

@@ -157,6 +157,29 @@ wasmtime_component_linker_add_wasip2(wasmtime_component_linker_t *linker);
 
 #endif // WASMTIME_FEATURE_WASI
 
+/// Type of the callback used in
+/// #wasmtime_component_linker_instance_add_resource
+typedef wasmtime_error_t *(*wasmtime_component_resource_destructor_t)(
+    void *, wasmtime_context_t *, uint32_t);
+
+/**
+ * \brief Defines a new resource type within this instance.
+ *
+ * This can be used to define a new resource type that the guest will be able
+ * to import. Here the `resource` is a type, often a host-defined type, which
+ * can be used to distinguish and definie different types of resources. A
+ * destruction callback is also specified via `destructor` which has private
+ * data `data` along with an optional `finalizer` for the `data` too.
+ *
+ * \return on success `NULL`, otherwise an error
+ */
+WASM_API_EXTERN wasmtime_error_t *
+wasmtime_component_linker_instance_add_resource(
+    wasmtime_component_linker_instance_t *linker_instance, const char *name,
+    size_t name_len, const wasmtime_component_resource_type_t *resource,
+    wasmtime_component_resource_destructor_t destructor, void *data,
+    void (*finalizer)(void *));
+
 /**
  * \brief Deletes a #wasmtime_component_linker_instance_t
  *

crates/c-api/include/wasmtime/component/linker.hh

@@ -116,6 +116,42 @@ public:
       return Error(error);
     }
 
+    return std::monostate();
+  }
+
+private:
+  template <typename F>
+  static wasmtime_error_t *
+  raw_resource_destructor_callback(void *env, wasmtime_context_t *store,
+                                   uint32_t rep) {
+    F *func = reinterpret_cast<F *>(env);
+    Result<std::monostate> result = (*func)(Store::Context(store), rep);
+    if (!result) {
+      return result.err().release();
+    }
+    return nullptr;
+  }
+
+public:
+  /// \brief Defines a new resource in this linker with the provided
+  /// destructor.
+  template <typename F,
+            std::enable_if_t<std::is_invocable_r_v<Result<std::monostate>, F,
+                                                   Store::Context, uint32_t>,
+                             bool> = true>
+  Result<std::monostate> add_resource(std::string_view name,
+                                      const ResourceType &ty, F &&f) {
+    auto *error = wasmtime_component_linker_instance_add_resource(
+        ptr.get(), name.data(), name.length(), ty.capi(),
+        raw_resource_destructor_callback<std::remove_reference_t<F>>,
+        std::make_unique<std::remove_reference_t<F>>(std::forward<F>(f))
+            .release(),
+        raw_finalize<std::remove_reference_t<F>>);
+
+    if (error != nullptr) {
+      return Error(error);
+    }
+
     return std::monostate();
   }
 };

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

@@ -9,11 +9,243 @@
 
 #include <stdint.h>
 #include <wasm.h>
+#include <wasmtime/store.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+/// \brief Represents the type of a component resource.
+///
+/// This is an opaque structure which represents the type of a resource. This
+/// can be used to equate the type of two resources together to see if they are
+/// the same.
+typedef struct wasmtime_component_resource_type
+    wasmtime_component_resource_type_t;
+
+/// \brief Creates a new resource type representing a host-defined resource.
+///
+/// This function creates a new `wasmtime_component_resource_type_t` which
+/// represents a host-defined resource identified by the `ty` integer argument
+/// provided. Two host resources with different `ty` arguments are considered
+/// not-equal in terms of resource types. Through this the host can create
+/// distinct types of resources at runtime to ensure that components are also
+/// required to keep resources distinct.
+///
+/// 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_type_new_host(uint32_t ty);
+
+/// \brief Clones a resource type.
+///
+/// Creates a new owned copy of a resource type.
+///
+/// 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_type_clone(
+    const wasmtime_component_resource_type_t *ty);
+
+/// \brief Compares two resource types for equality.
+///
+/// Returns whether `a` and `b` point to logically the same resource type under
+/// the hood.
+WASM_API_EXTERN
+bool wasmtime_component_resource_type_equal(
+    const wasmtime_component_resource_type_t *a,
+    const wasmtime_component_resource_type_t *b);
+
+/// \brief Deallocates a resource type.
+///
+/// This will deallocate the pointer `resource` any any memory that it might
+/// own.
+WASM_API_EXTERN
+void wasmtime_component_resource_type_delete(
+    wasmtime_component_resource_type_t *resource);
+
+/// \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;
 
@@ -80,6 +312,9 @@ typedef uint8_t wasmtime_component_valkind_t;
 /// \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
 
 struct wasmtime_component_val;
 struct wasmtime_component_valrecord_entry;
@@ -180,6 +415,9 @@ typedef union {
   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_RESOURCE
+  wasmtime_component_resource_any_t *resource;
 } wasmtime_component_valunion_t;
 
 /// \brief Represents possible runtime values which a component function can