Skip to content

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

Document some hazards of `Val` and `{Resource,Stream,Future}Any` (#14675)

Alex Crichton030d07cb1b35
diff --git a/crates/wasmtime/src/runtime/component/concurrent/future_stream_any.rs b/crates/wasmtime/src/runtime/component/concurrent/future_stream_any.rs
index b717fbcfad..7e63037c80 100644
--- a/crates/wasmtime/src/runtime/component/concurrent/future_stream_any.rs
+++ b/crates/wasmtime/src/runtime/component/concurrent/future_stream_any.rs
@@ -33,6 +33,11 @@ use wasmtime_environ::component::{
/// called then memory will not be leaked once the owning [`Store`] is dropped,
/// but the resource handle will be leaked until the [`Store`] is dropped.
///
+/// Note that special care should be taken when handling `FutureAny` in async
+/// functions. In this scenario an async host function can be cancelled
+/// (dropped) at any time and if a `FutureAny` it holds isn't closed then the
+/// future will be leaked within the store until the store is dropped.
+///
/// # Cloning
///
/// Cloning a [`FutureAny`] does not duplicate the underlying future: all clones
@@ -215,6 +220,11 @@ unsafe impl Lift for FutureAny {
/// called then memory will not be leaked once the owning [`Store`] is dropped,
/// but the resource handle will be leaked until the [`Store`] is dropped.
///
+/// Note that special care should be taken when handling `StreamAny` in async
+/// functions. In this scenario an async host function can be cancelled
+/// (dropped) at any time and if a `StreamAny` it holds isn't closed then the
+/// stream will be leaked within the store until the store is dropped.
+///
/// # Cloning
///
/// Cloning a [`StreamAny`] does not duplicate the underlying stream: all clones
diff --git a/crates/wasmtime/src/runtime/component/resources/any.rs b/crates/wasmtime/src/runtime/component/resources/any.rs
index 225825051f..5fdc02a52a 100644
--- a/crates/wasmtime/src/runtime/component/resources/any.rs
+++ b/crates/wasmtime/src/runtime/component/resources/any.rs
@@ -72,6 +72,15 @@ enum ResourceAnyIndex {
/// Borrows lifted from a component have host table state and must be dropped.
/// Synthetic borrows converted from [`Resource::new_borrow`] have no host table
/// state; calling `resource_drop` on one is harmless but unnecessary.
+///
+/// Note that special care should be taken when handling `ResourceAny` in async
+/// functions. In this scenario an async host function can be cancelled
+/// (dropped) at any time and if `ResourceAny` isn't destroyed then what it's
+/// referring to can leak within the store. If a `ResourceAny` is a borrow
+/// internally then failing to drop it, even on cancellation, will lead to a
+/// trap being raised and poisoning the store.
+///
+/// [`LinkerInstance::func_wrap_concurrent`]: crate::component::LinkerInstance::func_wrap_concurrent
#[derive(Debug, PartialEq, Eq, Copy, Clone)]
pub struct ResourceAny {
idx: ResourceAnyIndex,
diff --git a/crates/wasmtime/src/runtime/component/values.rs b/crates/wasmtime/src/runtime/component/values.rs
index 176350df72..607b09bc55 100644
--- a/crates/wasmtime/src/runtime/component/values.rs
+++ b/crates/wasmtime/src/runtime/component/values.rs
@@ -62,6 +62,16 @@ use wasmtime_environ::component::{
/// `Val` are type-checked against what's required by the component itself.
///
/// [`Func::call`]: crate::component::Func::call
+///
+/// # Ownership and handles
+///
+/// This type can contain handles to resources owned within a store, such as the
+/// `Resource`, `Future`, and `Stream` variants. For all of these variants it's
+/// required that when this `Val` is dropped that the corresponding resource in
+/// the store is additionally dropped, lest the handle is leaked within the
+/// store. This means that if you're receiving `Val`s you will need to be quite
+/// careful when dropping them or letting them go out of scope to handle this
+/// issue if it's applicable to your use case.
#[derive(Debug, Clone)]
#[expect(missing_docs, reason = "self-describing variants")]
pub enum Val {