A lightweight WebAssembly runtime that is fast, secure, and standards-compliant
Add docs for OOM-handling in Wasmtime (#13224)
Nick Fitzgerald42e40934cc83
diff --git a/crates/core/src/error/oom.rs b/crates/core/src/error/oom.rsindex 23e0aaaada..ae02c5caa1 100644--- a/crates/core/src/error/oom.rs+++ b/crates/core/src/error/oom.rs@@ -1,15 +1,95 @@use crate::error::{Error, OomOrDynError};use core::{fmt, mem, ptr::NonNull};-/// Out-of-memory error.+/// An out-of-memory (OOM) error.////// This error is the sentinel for allocation failure due to memory exhaustion.///-/// Constructing an [`Error`] from an `OutOfMemory` does not-/// allocate.+/// Constructing an [`Error`] from an `OutOfMemory` does not allocate.////// Allocation failure inside any `Error` method that must allocate/// (e.g. [`Error::context`]) will propagate an `OutOfMemory` error.+///+/// # Out-of-Memory Handling in Wasmtime+///+/// Wasmtime performs out-of-memory (OOM) error handling on a **best-effort+/// basis**. OOM handling does not have [tier 1+/// support](https://docs.wasmtime.dev/stability-tiers.html) at this time and,+/// therefore, while failure to handle OOM at some allocation site may be+/// considered a bug, and might be a potential denial-of-service vector, it+/// would not be considered a security vulnerability.[^limits]+///+/// [^limits]: Note that unconstrained guest-controlled resource usage is still+/// considered a vulnerability. Wasmtime has tier 1 support for limiting guest+/// resources, but not for handling OOMs within those limits.+///+/// ## Where Wasmtime Attempts to Handle OOM+///+/// It is important to note that **not all portions of Wasmtime attempt to+/// handle out-of-memory errors**. Notably, Wasmtime only ever attempts to+/// handle OOM in the core *runtime* and never in the *compiler*. No attempt is+/// made to handle allocation failure in the middle of compiling new `Module`s+/// or `Component`s from Wasm to machine code (or Pulley bytecode). However,+/// Wasmtime will attempt to handle OOM when running *pre-compiled* Wasm code+/// (loaded via `Module::deserialize` or `Component::deserialize`).+///+/// Wasmtime's interfaces allow *you* to handle OOM in your own embedding's WASI+/// implementations and host APIs, but Wasmtime's provided WASI implementations+/// (e.g. `wasmtime_wasi_http`) will generally not attempt to handle OOM (as+/// they often depend on third-party crates that do not attempt to handle OOM).+///+/// The API documentation for individual functions and methods that handle OOM+/// should generally document this fact by listing `OutOfMemory` as one of the+/// potential errors returned.+///+/// | **Where** | **Handles OOM?** |+/// |-------------------------------------------------|---------------------------------|+/// | **Compiler** | **No** |+/// |  `wasmtime::Module::new` | No |+/// |  `wasmtime::Component::new` | No |+/// |  `wasmtime::CodeBuilder` | No |+/// |  Other compilation APIs... | No |+/// | **Runtime** | **Yes** |+/// |  `wasmtime::Store` | Yes |+/// |  `wasmtime::Linker` | Yes |+/// |  `wasmtime::Module::deserialize` | Yes |+/// |  `wasmtime::Instance` | Yes |+/// |  `wasmtime::Func::call` | Yes |+/// |  Component Model concurrency/async APIs | Not yet |+/// |  Other instantiation and execution APIs... | Yes |+/// | **WASI Implementations and Host APIs** | **Depends** |+/// |  `wasmtime_wasi` | No |+/// |  `wasmtime_wasi_http` | No |+/// |  `wasmtime_wasi_*` | No |+/// |  Your embedding's APIs | If *you* implement OOM handling |+///+/// If you encounter an unhandled OOM inside Wasmtime, and it is within a+/// portion of code where it should be handled, then please [file an+/// issue](https://github.com/bytecodealliance/wasmtime/issues/new/choose).+///+/// ## Handling More OOMs with Rust Nightly APIs+///+/// Rust's standard library provides fallible allocation APIs, or the necessary+/// building blocks for making our own fallible allocation APIs, for some of its+/// types and collections. For example, it provides `Vec::try_reserve` which can+/// be used to build a fallible version of `Vec::push` and fallible `Box`+/// allocation can be built upon raw allocations from the global allocator and+/// `Box::from_raw`.+///+/// However, the standard library does not provide these things for all the+/// types and collections that Wasmtime uses. Some of these APIs are completely+/// missing (such as a fallible version of+/// `std::collections::hash_map::VacantEntry::insert`) and some APIs exist but+/// are feature-gated on unstable, nightly-only Rust features. The most relevant+/// API from this latter category is+/// [`Arc::try_new`](https://doc.rust-lang.org/nightly/std/sync/struct.Arc.html#method.try_new),+/// as Wasmtime's runtime uses a number of `Arc`s under the covers.+///+/// If handling OOMs is important for your Wasmtime embedding, then you should+/// compile Wasmtime from source using a Nightly Rust toolchain and with the+/// `RUSTFLAGS="--cfg arc_try_new"` environment variable set. This unlocks+/// Wasmtime's internal usage of `Arc::try_new`, making more OOM handling at+/// more allocation sites possible.#[derive(Clone, Copy)]// NB: `OutOfMemory`'s representation must be the same as `OomOrDynError`// (and therefore also `Error`).diff --git a/crates/wasmtime/src/engine.rs b/crates/wasmtime/src/engine.rsindex cb68341695..9bdeff4d2d 100644--- a/crates/wasmtime/src/engine.rs+++ b/crates/wasmtime/src/engine.rs@@ -101,6 +101,10 @@ impl Engine {/// For example, feature `reference_types` will need to set/// the compiler setting `unwind_info` to `true`, but explicitly/// disable these two compiler settings will cause errors.+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn new(config: &Config) -> Result<Engine> {let config = config.clone();let (mut tunables, features) = config.validate()?;diff --git a/crates/wasmtime/src/lib.rs b/crates/wasmtime/src/lib.rsindex 8ae924c4fd..175fd37032 100644--- a/crates/wasmtime/src/lib.rs+++ b/crates/wasmtime/src/lib.rs@@ -520,7 +520,7 @@ pub use wasmtime_environ::{FuncIndex, StaticModuleIndex};#[cfg(feature = "anyhow")]pub use wasmtime_environ::anyhow;-pub use self::error::{Error, Result, bail, ensure, format_err};+pub use self::error::{Error, OutOfMemory, Result, bail, ensure, format_err};/// A re-exported instance of Wasmtime's `wasmparser` dependency.///diff --git a/crates/wasmtime/src/runtime/component/component.rs b/crates/wasmtime/src/runtime/component/component.rsindex 1b5511e9ff..cbf29f5425 100644--- a/crates/wasmtime/src/runtime/component/component.rs+++ b/crates/wasmtime/src/runtime/component/component.rs@@ -206,6 +206,12 @@ impl Component {////// For more information see the [`Module::deserialize`] method.///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Unsafety////// The unsafety of this method is the same as that of thediff --git a/crates/wasmtime/src/runtime/component/func.rs b/crates/wasmtime/src/runtime/component/func.rsindex 0b8a116461..0513dfbc9d 100644--- a/crates/wasmtime/src/runtime/component/func.rs+++ b/crates/wasmtime/src/runtime/component/func.rs@@ -91,6 +91,10 @@ impl Func {/// If the function does not actually take `Params` as its parameters or/// return `Return` then an error will be returned.///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// This function will panic if `self` is not owned by the `store`@@ -223,6 +227,10 @@ impl Func {/// See [`TypedFunc::call`] for more information in addition to/// [`wasmtime::Func::call`](crate::Func::call).///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// Panics if `store` does not own this function.@@ -240,6 +248,12 @@ impl Func {/// Exactly like [`Self::call`] except for use on async stores.///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// Panics if `store` does not own this function.diff --git a/crates/wasmtime/src/runtime/component/func/typed.rs b/crates/wasmtime/src/runtime/component/func/typed.rsindex 307bffa563..2aca97603c 100644--- a/crates/wasmtime/src/runtime/component/func/typed.rs+++ b/crates/wasmtime/src/runtime/component/func/typed.rs@@ -140,6 +140,10 @@ where/// information to understand which part of the canonical ABI went wrong/// and what to inspect.///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// Panics if `store` does not own this function.@@ -152,6 +156,12 @@ where/// Exactly like [`Self::call`], except for invoking WebAssembly/// [asynchronously](crate#async).///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// Panics if `store` does not own this function.diff --git a/crates/wasmtime/src/runtime/component/instance.rs b/crates/wasmtime/src/runtime/component/instance.rsindex 0a94bcb4ff..3b102fb64c 100644--- a/crates/wasmtime/src/runtime/component/instance.rs+++ b/crates/wasmtime/src/runtime/component/instance.rs@@ -182,6 +182,10 @@ impl Instance {/// Returns an error if `name` isn't a function export or if the export's/// type did not match `Params` or `Results`///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// Panics if `store` does not own this instance.@@ -1159,6 +1163,12 @@ impl<T: 'static> InstancePre<T> {}/// Performs the instantiation process into the store specified.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.//// TODO: needs more docspub fn instantiate(&self, mut store: impl AsContextMut<Data = T>) -> Result<Instance> {@@ -1175,6 +1185,12 @@ impl<T: 'static> InstancePre<T> {/// Performs the instantiation process into the store specified.////// Exactly like [`Self::instantiate`] except for use on async stores.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.//// TODO: needs more docs#[cfg(feature = "async")]diff --git a/crates/wasmtime/src/runtime/component/linker.rs b/crates/wasmtime/src/runtime/component/linker.rsindex f17aba36df..889cfc8a71 100644--- a/crates/wasmtime/src/runtime/component/linker.rs+++ b/crates/wasmtime/src/runtime/component/linker.rs@@ -186,6 +186,12 @@ impl<T: 'static> Linker<T> {/// Returns the [`types::Component`] corresponding to `component` with resource/// types imported by it replaced using imports present in [`Self`].+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn substituted_component_type(&self, component: &Component) -> Result<types::Component> {let cx = self.typecheck(&component)?;Ok(types::Component::from(@@ -215,6 +221,10 @@ impl<T: 'static> Linker<T> {/// Returns an error if this linker doesn't define a name that the/// `component` imports or if a name defined doesn't match the type of the/// item imported by the `component` provided.+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn instantiate_pre(&self, component: &Component) -> Result<InstancePre<T>> {let cx = self.typecheck(&component)?;@@ -279,6 +289,10 @@ impl<T: 'static> Linker<T> {/// `component` requires or if it is of the wrong type. Additionally this/// can return an error if something goes wrong during instantiation such as/// a runtime trap or a runtime limit being exceeded.+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn instantiate(&self,mut store: impl AsContextMut<Data = T>,@@ -300,6 +314,10 @@ impl<T: 'static> Linker<T> {/// `component` requires or if it is of the wrong type. Additionally this/// can return an error if something goes wrong during instantiation such as/// a runtime trap or a runtime limit being exceeded.+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.#[cfg(feature = "async")]pub async fn instantiate_async(&self,@@ -318,6 +336,12 @@ impl<T: 'static> Linker<T> {////// By default a [`Linker`] will error when unknown imports are encountered when instantiating a [`Component`]./// This changes this behavior from an instant error to a trap that will happen if the import is called.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn define_unknown_imports_as_traps(&mut self, component: &Component) -> Result<()> {use wasmtime_environ::component::ComponentTypes;use wasmtime_environ::component::TypeDef;@@ -433,6 +457,12 @@ impl<T: 'static> LinkerInstance<'_, T> {/// guest, see the [`func_wrap_async`] method.////// [`func_wrap_async`]: LinkerInstance::func_wrap_async+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.//// TODO: needs more words and examplespub fn func_wrap<F, Params, Return>(&mut self, name: &str, func: F) -> Result<()>@@ -656,6 +686,12 @@ impl<T: 'static> LinkerInstance<'_, T> {/// # Ok(())/// # }/// ```+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn func_new(&mut self,name: &str,@@ -724,6 +760,12 @@ impl<T: 'static> LinkerInstance<'_, T> {/// This can be used to provide a core wasm [`Module`] as an import to a/// component. The [`Module`] provided is saved within the linker for the/// specified `name` in this instance.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn module(&mut self, name: &str, module: &Module) -> Result<()> {self.insert(name, Definition::Module(module.clone()))?;Ok(())@@ -751,6 +793,10 @@ impl<T: 'static> LinkerInstance<'_, T> {/// The provided `dtor` closure returns an error if something goes wrong/// when a guest calls the `dtor` to drop a `Resource<T>` such as/// a runtime trap or a runtime limit being exceeded.+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn resource(&mut self,name: &str,diff --git a/crates/wasmtime/src/runtime/component/resources/any.rs b/crates/wasmtime/src/runtime/component/resources/any.rsindex 17c933f134..cc84cecb89 100644--- a/crates/wasmtime/src/runtime/component/resources/any.rs+++ b/crates/wasmtime/src/runtime/component/resources/any.rs@@ -72,6 +72,10 @@ impl ResourceAny {/// This method will return an error if `resource` has already been "taken"/// and has ownership transferred elsewhere which can happen in situations/// such as when it's already lowered into a component.+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn try_from_resource<T: 'static>(resource: Resource<T>,store: impl AsContextMut,@@ -80,6 +84,12 @@ impl ResourceAny {}/// See [`Resource::try_from_resource_any`]+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn try_into_resource<T: 'static>(self, store: impl AsContextMut) -> Result<Resource<T>> {Resource::try_from_resource_any(self, store)}@@ -146,6 +156,12 @@ impl ResourceAny {/// properly cleaned up. For owned resources this may execute the/// guest-defined destructor if applicable (or the host-defined destructor/// if one was specified).+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn resource_drop(self, mut store: impl AsContextMut) -> Result<()> {let mut store = store.as_context_mut();store.0.validate_sync_call()?;@@ -154,6 +170,12 @@ impl ResourceAny {/// Same as [`ResourceAny::resource_drop`] except for use with async stores/// to execute the destructor [asynchronously](crate#async).+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.#[cfg(feature = "async")]pub async fn resource_drop_async(self, mut store: impl AsContextMut<Data: Send>) -> Result<()> {let mut store = store.as_context_mut();diff --git a/crates/wasmtime/src/runtime/externals/global.rs b/crates/wasmtime/src/runtime/externals/global.rsindex e0a9991d8a..4bca75875c 100644--- a/crates/wasmtime/src/runtime/externals/global.rs+++ b/crates/wasmtime/src/runtime/externals/global.rs@@ -59,6 +59,10 @@ impl Global {/// Returns an error if the `ty` provided does not match the type of the/// value `val`, or if `val` comes from a different store than `store`.///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Examples////// ```@@ -216,6 +220,10 @@ impl Global {/// it's not a mutable global, or if `val` comes from a different store than/// the one provided.///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// Panics if `store` does not own this global.diff --git a/crates/wasmtime/src/runtime/externals/table.rs b/crates/wasmtime/src/runtime/externals/table.rsindex 98202ba71b..293f6c90ab 100644--- a/crates/wasmtime/src/runtime/externals/table.rs+++ b/crates/wasmtime/src/runtime/externals/table.rs@@ -65,6 +65,10 @@ impl Table {/// [`Store::limiter_async`](`crate::Store::limiter_async`). When using an/// async resource limiter, use [`Table::new_async`] instead.///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Examples////// ```@@ -103,6 +107,12 @@ impl Table {////// You must use this variant with [`Store`](`crate::Store`)s which have a/// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`).+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.#[cfg(feature = "async")]pub async fn new_async(mut store: impl AsContextMut,@@ -212,6 +222,10 @@ impl Table {/// the right type to be stored in this table, or if `val` belongs to a/// different store.///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// Panics if `store` does not own this table.@@ -277,6 +291,10 @@ impl Table {/// [`Store::limiter_async`](`crate::Store::limiter_async`)). When using an/// async resource limiter, use [`Table::grow_async`] instead.///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// Panics if `store` does not own this table.@@ -344,6 +362,12 @@ impl Table {/// Required when using a/// [`ResourceLimiterAsync`](`crate::ResourceLimiterAsync`).///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// This function will panic when if the store doesn't own the table.@@ -366,6 +390,10 @@ impl Table {/// destination tables, or if the source table's element type does not match/// the destination table's element type.///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// Panics if `store` does not own either `dst_table` or `src_table`.@@ -489,6 +517,10 @@ impl Table {////// * `val` comes from a different `Store` from this table.///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// Panics if `store` does not own either `dst_table` or `src_table`.diff --git a/crates/wasmtime/src/runtime/externals/tag.rs b/crates/wasmtime/src/runtime/externals/tag.rsindex a89d372ee9..0c6d8814df 100644--- a/crates/wasmtime/src/runtime/externals/tag.rs+++ b/crates/wasmtime/src/runtime/externals/tag.rs@@ -24,6 +24,12 @@ impl Tag {}/// Create a new tag instance from a given TagType.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn new(mut store: impl AsContextMut, ty: &TagType) -> Result<Tag> {generate_tag_export(store.as_context_mut().0, ty)}diff --git a/crates/wasmtime/src/runtime/func.rs b/crates/wasmtime/src/runtime/func.rsindex 7e48f0d8eb..a0ec000c98 100644--- a/crates/wasmtime/src/runtime/func.rs+++ b/crates/wasmtime/src/runtime/func.rs@@ -381,6 +381,12 @@ impl Func {/// Same as [`Func::new`] but returns an error instead of panicking on/// allocation failure.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn try_new<T: 'static>(store: impl AsContextMut<Data = T>,ty: FuncType,@@ -814,6 +820,12 @@ impl Func {/// Fallible version of [`Func::wrap`] that returns an error on/// out-of-memory instead of panicking.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn try_wrap<T, Params, Results>(mut store: impl AsContextMut<Data = T>,func: impl IntoFunc<T, Params, Results>,@@ -942,6 +954,10 @@ impl Func {/// Panics if `store` does not own this function.////// [`WasmBacktrace`]: crate::WasmBacktrace+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn call(&self,mut store: impl AsContextMut,@@ -1089,6 +1105,10 @@ impl Func {/// Panics if this is called on a function in a synchronous store. This/// only works with functions defined within an asynchronous store. Also/// panics if `store` does not own this function.+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.#[cfg(feature = "async")]pub async fn call_async(&self,diff --git a/crates/wasmtime/src/runtime/func/typed.rs b/crates/wasmtime/src/runtime/func/typed.rsindex fa0d4b10bd..b8058da690 100644--- a/crates/wasmtime/src/runtime/func/typed.rs+++ b/crates/wasmtime/src/runtime/func/typed.rs@@ -92,6 +92,10 @@ where/// Panics if `store` does not contain this function.////// [`Trap`]: crate::Trap+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.#[inline]pub fn call(&self, mut store: impl AsContextMut, params: Params) -> Result<Results> {let mut store = store.as_context_mut();@@ -117,6 +121,10 @@ where/// connected to a synchronous store.////// [`Trap`]: crate::Trap+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.#[cfg(feature = "async")]pub async fn call_async(&self,diff --git a/crates/wasmtime/src/runtime/instance.rs b/crates/wasmtime/src/runtime/instance.rsindex 4d10374c9e..6d67feed45 100644--- a/crates/wasmtime/src/runtime/instance.rs+++ b/crates/wasmtime/src/runtime/instance.rs@@ -109,6 +109,10 @@ impl Instance {////// [inst]: https://webassembly.github.io/spec/core/exec/modules.html#exec-instantiation/// [`ExternType`]: crate::ExternType+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn new(mut store: impl AsContextMut,module: &Module,@@ -187,6 +191,12 @@ impl Instance {////// fn assert_send<T: Send>(t: T) -> T { t }/// ```+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.#[cfg(feature = "async")]pub async fn new_async(mut store: impl AsContextMut,@@ -521,6 +531,12 @@ impl Instance {/// # Panics////// Panics if `store` does not own this instance.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn get_typed_func<Params, Results>(&self,mut store: impl AsContextMut,@@ -891,6 +907,12 @@ impl<T: 'static> InstancePre<T> {/// `store`, or if `store` has async support enabled. Additionally this/// function will panic if the `store` provided comes from a different/// [`Engine`] than the [`InstancePre`] originally came from.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn instantiate(&self, mut store: impl AsContextMut<Data = T>) -> Result<Instance> {let mut store = store.as_context_mut();let imports = pre_instantiate_raw(@@ -926,6 +948,12 @@ impl<T: 'static> InstancePre<T> {////// Panics if any import closed over by this [`InstancePre`] isn't owned by/// `store`, or if `store` does not have async support enabled.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.#[cfg(feature = "async")]pub async fn instantiate_async(&self,diff --git a/crates/wasmtime/src/runtime/linker.rs b/crates/wasmtime/src/runtime/linker.rsindex 184442c875..2ab5d83554 100644--- a/crates/wasmtime/src/runtime/linker.rs+++ b/crates/wasmtime/src/runtime/linker.rs@@ -355,6 +355,10 @@ impl<T> Linker<T> {/// # Ok(())/// # }/// ```+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn define(&mut self,store: impl AsContext<Data = T>,@@ -377,6 +381,12 @@ impl<T> Linker<T> {/// This is only relevant when working with the module linking proposal/// where one-level names are allowed (in addition to two-level names)./// Otherwise this method need not be used.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn define_name(&mut self,store: impl AsContext<Data = T>,@@ -409,6 +419,12 @@ impl<T> Linker<T> {////// Panics if the given function type is not associated with the same engine/// as this linker.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn func_new(&mut self,module: &str,@@ -537,6 +553,10 @@ impl<T> Linker<T> {/// # Ok(())/// # }/// ```+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn func_wrap<Params, Args>(&mut self,module: &str,@@ -623,6 +643,10 @@ impl<T> Linker<T> {/// # Ok(())/// # }/// ```+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn instance(&mut self,mut store: impl AsContextMut<Data = T>,@@ -833,6 +857,12 @@ impl<T> Linker<T> {/// Define automatic instantiations of a [`Module`] in this linker.////// This is the same as [`Linker::module`], except for async `Store`s.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.#[cfg(feature = "async")]pub async fn module_async(&mut self,@@ -960,6 +990,10 @@ impl<T> Linker<T> {////// Returns an error if any shadowing violations happen while defining new/// items, or if the original item wasn't defined.+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn alias(&mut self,module: &str,@@ -985,6 +1019,10 @@ impl<T> Linker<T> {////// Returns an error if any shadowing violations happen while defining new/// items.+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn alias_module(&mut self, module: &str, as_module: &str) -> Result<()> {let module = self.pool.insert(module)?;let as_module = self.pool.insert(as_module)?;@@ -1090,6 +1128,12 @@ impl<T> Linker<T> {/// Attempts to instantiate the `module` provided. This is the same as/// [`Linker::instantiate`], except for async `Store`s.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.#[cfg(feature = "async")]pub async fn instantiate_async(&self,@@ -1151,6 +1195,10 @@ impl<T> Linker<T> {/// # Ok(())/// # }/// ```+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn instantiate_pre(&self, module: &Module) -> Result<InstancePre<T>>whereT: 'static,@@ -1231,6 +1279,12 @@ impl<T> Linker<T> {////// This function will panic if the `store` provided does not come from the/// same [`Engine`] that this linker was created with.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn get(&self,mut store: impl AsContextMut<Data = T>,@@ -1279,6 +1333,12 @@ impl<T> Linker<T> {/// Same as [`Linker::get_by_import`] but returns an error instead of/// panicking on allocation failure.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn try_get_by_import(&self,mut store: impl AsContextMut<Data = T>,@@ -1312,6 +1372,12 @@ impl<T> Linker<T> {/// Panics if the default function found is not owned by `store`. This/// function will also panic if the `store` provided does not come from the/// same [`Engine`] that this linker was created with.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn get_default(&self, mut store: impl AsContextMut<Data = T>, module: &str) -> Result<Func>whereT: 'static,diff --git a/crates/wasmtime/src/runtime/memory.rs b/crates/wasmtime/src/runtime/memory.rsindex 81cb628896..ab418253d4 100644--- a/crates/wasmtime/src/runtime/memory.rs+++ b/crates/wasmtime/src/runtime/memory.rs@@ -260,6 +260,12 @@ impl Memory {/// # Ok(())/// # }/// ```+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn new(mut store: impl AsContextMut, ty: MemoryType) -> Result<Memory> {let (mut limiter, store) = store.as_context_mut()@@ -276,6 +282,12 @@ impl Memory {////// This function will panic when used with a non-async/// [`Store`](`crate::Store`).+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.#[cfg(feature = "async")]pub async fn new_async(mut store: impl AsContextMut, ty: MemoryType) -> Result<Memory> {let (mut limiter, store) = store.as_context_mut().0.resource_limiter_and_store_opaque();@@ -330,6 +342,12 @@ impl Memory {/// If `offset + buffer.len()` exceed the current memory capacity, then the/// buffer is left untouched and a [`MemoryAccessError`] is returned.///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// Panics if this memory doesn't belong to `store`.@@ -355,6 +373,12 @@ impl Memory {/// none of the buffer is written to memory and a [`MemoryAccessError`] is/// returned.///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// Panics if this memory doesn't belong to `store`.@@ -582,6 +606,10 @@ impl Memory {/// [`Store::limiter_async`](`crate::Store::limiter_async`). When using an/// async resource limiter, use [`Memory::grow_async`] instead.///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.+ ////// # Panics////// Panics if this memory doesn't belong to `store`.@@ -619,6 +647,12 @@ impl Memory {////// This function will panic when used with a non-async/// [`Store`](`crate::Store`).+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.#[cfg(feature = "async")]pub async fn grow_async(&self, mut store: impl AsContextMut, delta: u64) -> Result<u64> {let store = store.as_context_mut();@@ -831,6 +865,12 @@ impl SharedMemory {/// Construct a [`SharedMemory`] by providing both the `minimum` and/// `maximum` number of 64K-sized pages. This call allocates the necessary/// pages on the system.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.#[cfg(feature = "threads")]pub fn new(engine: &Engine, ty: MemoryType) -> Result<Self> {if !ty.is_shared() {@@ -923,6 +963,10 @@ impl SharedMemory {/// the maximum limits of this memory. A/// [`ResourceLimiter`](crate::ResourceLimiter) is another example of/// preventing a memory to grow.+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn grow(&self, delta: u64) -> Result<u64> {match self.vm.grow(delta)? {Some((old_size, _new_size)) => {diff --git a/crates/wasmtime/src/runtime/module.rs b/crates/wasmtime/src/runtime/module.rsindex 79202c64b8..a34e68c7cd 100644--- a/crates/wasmtime/src/runtime/module.rs+++ b/crates/wasmtime/src/runtime/module.rs@@ -404,6 +404,12 @@ impl Module {/// those defined by any version of wasmtime. (this means that if you cache/// blobs across versions of wasmtime you can be safely guaranteed that/// future versions of wasmtime will reject old cache entries).+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub unsafe fn deserialize(engine: &Engine, bytes: impl AsRef<[u8]>) -> Result<Module> {let code = engine.load_code_bytes(bytes.as_ref(), ObjectKind::Module)?;Module::from_parts(engine, code, None)diff --git a/crates/wasmtime/src/runtime/store.rs b/crates/wasmtime/src/runtime/store.rsindex f4848de5dd..b9cfdb1974 100644--- a/crates/wasmtime/src/runtime/store.rs+++ b/crates/wasmtime/src/runtime/store.rs@@ -736,6 +736,12 @@ impl<T> Store<T> {}/// Like `Store::new` but returns an error on allocation failure.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn try_new(engine: &Engine, data: T) -> Result<Self> {let store_data = StoreData::new(engine);log::trace!("creating new store {:?}", store_data.id());@@ -1034,6 +1040,10 @@ impl<T> Store<T> {////// This function will return an error if fuel consumption is not enabled/// via [`Config::consume_fuel`](crate::Config::consume_fuel).+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn get_fuel(&self) -> Result<u64> {self.inner.get_fuel()}@@ -1057,6 +1067,10 @@ impl<T> Store<T> {////// This function will return an error if fuel consumption is not enabled via/// [`Config::consume_fuel`](crate::Config::consume_fuel).+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn set_fuel(&mut self, fuel: u64) -> Result<()> {self.inner.set_fuel(fuel)}diff --git a/crates/wasmtime/src/runtime/types.rs b/crates/wasmtime/src/runtime/types.rsindex 601c1c0268..040bd0823c 100644--- a/crates/wasmtime/src/runtime/types.rs+++ b/crates/wasmtime/src/runtime/types.rs@@ -2413,6 +2413,12 @@ impl FuncType {/// Like [`FuncType::new`] but returns an/// [`OutOfMemory`][crate::error::OutOfMemory] error on allocation failure.+ ///+ /// # Errors+ ///+ /// This function will return an [`OutOfMemory`][crate::OutOfMemory] error when+ /// memory allocation fails. See the `OutOfMemory` type's documentation for+ /// details on Wasmtime's out-of-memory handling.pub fn try_new(engine: &Engine,params: impl IntoIterator<Item = ValType>,