Skip to content

A lightweight WebAssembly runtime that is fast, secure, and standards-compliant

component: document ownership of exported guest resources (#14434)

B. Nautc7ff273e233b
diff --git a/crates/wasmtime/src/runtime/component/bindgen_examples/_6_exported_resources.rs b/crates/wasmtime/src/runtime/component/bindgen_examples/_6_exported_resources.rs
index 576450cc66..66be19cbed 100644
--- a/crates/wasmtime/src/runtime/component/bindgen_examples/_6_exported_resources.rs
+++ b/crates/wasmtime/src/runtime/component/bindgen_examples/_6_exported_resources.rs
@@ -13,6 +13,7 @@ bindgen!({
warn,
error,
}
+
resource logger {
constructor(max-level: level);
@@ -21,6 +22,10 @@ bindgen!({
log: func(level: level, msg: string);
}
+
+ inspect-logger: func(logger: borrow<logger>) -> level;
+ take-logger: func(logger: logger);
+ get-default-logger: func() -> logger;
}
"#,
});
diff --git a/crates/wasmtime/src/runtime/component/bindgen_examples/mod.rs b/crates/wasmtime/src/runtime/component/bindgen_examples/mod.rs
index efc7e9d102..6bbba5b291 100644
--- a/crates/wasmtime/src/runtime/component/bindgen_examples/mod.rs
+++ b/crates/wasmtime/src/runtime/component/bindgen_examples/mod.rs
@@ -450,7 +450,9 @@ pub mod _5_all_world_export_kinds;
/// example to [`GuestLogger`] here.
/// * Resource-related methods all take a [`ResourceAny`] as an argument or
/// a return value.
-/// * The [`ResourceAny`] must be explicitly dropped.
+/// * The WIT signature determines ownership. A `logger` parameter transfers
+/// ownership, while `borrow<logger>` borrows the resource for one call.
+/// * The host must explicitly drop each owned [`ResourceAny`] it retains.
///
/// [`ResourceAny`]: crate::component::ResourceAny
/// [`Guest`]: _6_exported_resources::exports::example::exported_resources::logging::Guest
@@ -479,6 +481,21 @@ pub mod _5_all_world_export_kinds;
/// let guest = bindings.example_exported_resources_logging();
/// let logger = guest.logger();
///
+/// // Free interface functions are methods on `guest`. A function that
+/// // returns a WIT `logger` gives the host an owned `ResourceAny`.
+/// let returned_logger = guest.call_get_default_logger(&mut store)?;
+///
+/// // Both `logger` and `borrow<logger>` parameters are `ResourceAny` in
+/// // Rust, so the WIT signature determines ownership. `inspect-logger`
+/// // takes `borrow<logger>`, so the host keeps ownership after this call.
+/// let max_level = guest.call_inspect_logger(&mut store, returned_logger)?;
+/// logger.call_log(&mut store, returned_logger, max_level, "hello!")?;
+///
+/// // The host must either drop an owned resource or transfer it back to
+/// // the guest. This also applies to resources nested in records,
+/// // variants, lists, and other values.
+/// returned_logger.resource_drop(&mut store)?;
+///
/// // Resource methods are all attached to `logger` and take the
/// // `ResourceAny` parameter explicitly.
/// let my_logger = logger.call_constructor(&mut store, Level::Warn)?;
@@ -487,9 +504,10 @@ pub mod _5_all_world_export_kinds;
///
/// logger.call_log(&mut store, my_logger, Level::Debug, "hello!")?;
///
-/// // The `ResourceAny` type has no destructor but when the host is done
-/// // with it it needs to invoke the guest-level destructor.
-/// my_logger.resource_drop(&mut store)?;
+/// // `take-logger` takes an owned WIT `logger`, so this call transfers
+/// // ownership to the guest. `ResourceAny` is `Copy`, but the host must
+/// // not drop or reuse `my_logger` afterwards.
+/// guest.call_take_logger(&mut store, my_logger)?;
///
/// Ok(())
/// }
diff --git a/crates/wasmtime/src/runtime/component/resources/any.rs b/crates/wasmtime/src/runtime/component/resources/any.rs
index 2c22f2c5a3..232abecd52 100644
--- a/crates/wasmtime/src/runtime/component/resources/any.rs
+++ b/crates/wasmtime/src/runtime/component/resources/any.rs
@@ -27,25 +27,47 @@ enum ResourceAnyIndex {
Borrow(u32),
}
-/// Representation of a resource in the component model, either a guest-defined
-/// or a host-defined resource.
+/// Representation of a dynamically typed guest-defined or host-defined
+/// resource in the component model.
///
-/// This type is similar to [`Resource`] except that it can be used to represent
-/// any resource, either host or guest. This type cannot be directly constructed
-/// and is only available if the guest returns it to the host (e.g. a function
-/// returning a guest-defined resource) or by a conversion from [`Resource`] via
-/// [`ResourceAny::try_from_resource`].
-/// This type also does not carry a static type parameter `T` for example and
-/// does not have as much information about its type.
-/// This means that it's possible to get runtime type-errors when
-/// using this type because it cannot statically prevent mismatching resource
-/// types.
+/// # Guest-defined resources
+///
+/// Guest-defined resources enter the host through generated bindings, such as
+/// a function that returns an owned resource. Their methods are called through
+/// the generated type for that resource, for example `GuestLogger` in the
+/// exported resources example in [`bindgen_examples`]. A guest-defined
+/// [`ResourceAny`] cannot be converted to [`Resource`] or [`ResourceDynamic`],
+/// because those types represent host-defined resources.
+///
+/// [`bindgen_examples`]: crate::component::bindgen_examples
+///
+/// # Host-defined resources
+///
+/// Convert a host-defined [`Resource<T>`](Resource) to this type with
+/// [`ResourceAny::try_from_resource`]. Convert it back with
+/// [`ResourceAny::try_into_resource`] or
+/// [`ResourceAny::try_into_resource_dynamic`]. These conversions check the
+/// resource type at runtime.
+///
+/// # Ownership and destruction
///
/// Like [`Resource`] this type represents either an `own` or a `borrow`
-/// resource internally. A [`ResourceAny`] with a host table entry must be
-/// explicitly destroyed with [`ResourceAny::resource_drop`] (or converted to
-/// a typed resource). This updates dynamic state tracking and invokes the
-/// WebAssembly-defined destructor for a resource, if any.
+/// resource internally, and the WIT signature controls which one a value is.
+/// Passing a resource to an `own` parameter transfers ownership to the callee,
+/// while passing it to a `borrow` parameter keeps ownership with the caller.
+/// When a function returns an `own` resource, the caller acquires ownership.
+/// The same applies to each owned resource nested in a record, variant, list,
+/// or other value.
+///
+/// A [`ResourceAny`] with a host table entry that the host still owns must
+/// eventually be passed to an `own` parameter, converted to a typed resource,
+/// or explicitly destroyed with [`ResourceAny::resource_drop`]. Destroying it
+/// updates dynamic state tracking and invokes the WebAssembly-defined
+/// destructor for a resource, if any. `ResourceAny` is `Copy`, but once
+/// ownership has been transferred the handle must not be used again.
+///
+/// `ResourceAny` has no static type parameter, so using one with the wrong
+/// generated function produces a runtime type error.
///
/// Borrows lifted from a component have host table state and must be dropped.
/// Synthetic borrows converted from [`Resource::new_borrow`] have no host table
@@ -74,15 +96,14 @@ impl ResourceAny {
}
}
- /// Attempts to convert an imported [`Resource`] into [`ResourceAny`].
+ /// Attempts to convert a host-defined [`Resource`] into [`ResourceAny`].
///
/// * `resource` is the resource to convert.
/// * `store` is the store to place the returned resource into.
///
- /// The returned `ResourceAny` will not have a destructor attached to it
- /// meaning that if `resource_drop` is called then it will not invoked a
- /// host-defined destructor. This is similar to how `Resource<T>` does not
- /// have a destructor associated with it.
+ /// The returned `ResourceAny` has no destructor attached to it, so
+ /// `resource_drop` will not invoke a host-defined destructor. This matches
+ /// [`Resource`], which has no associated destructor.
///
/// # Errors
///
@@ -100,7 +121,12 @@ impl ResourceAny {
resource.try_into_resource_any(store)
}
- /// See [`Resource::try_from_resource_any`]
+ /// Attempts to convert this value into a statically typed, host-defined
+ /// [`Resource`].
+ ///
+ /// This conversion accepts only host-defined resources of type `T`.
+ /// Guest-defined resources must remain [`ResourceAny`] values and be used
+ /// through their generated functions and resource projection.
///
/// # Errors
///
@@ -111,7 +137,12 @@ impl ResourceAny {
Resource::try_from_resource_any(self, store)
}
- /// See [`ResourceDynamic::try_from_resource_any`]
+ /// Attempts to convert this value into a dynamically typed, host-defined
+ /// [`ResourceDynamic`].
+ ///
+ /// This conversion accepts only host-defined resources. Guest-defined
+ /// resources must remain [`ResourceAny`] values and be used through their
+ /// generated functions and resource projection.
pub fn try_into_resource_dynamic(self, store: impl AsContextMut) -> Result<ResourceDynamic> {
ResourceDynamic::try_from_resource_any(self, store)
}