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.rsindex 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 clonesdiff --git a/crates/wasmtime/src/runtime/component/resources/any.rs b/crates/wasmtime/src/runtime/component/resources/any.rsindex 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.rsindex 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 {