Skip to content

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.rs
index 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.rs
index 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.rs
index 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.rs
index 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 the
diff --git a/crates/wasmtime/src/runtime/component/func.rs b/crates/wasmtime/src/runtime/component/func.rs
index 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.rs
index 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.rs
index 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 docs
pub 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.rs
index 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 examples
pub 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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>>
where
T: '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>
where
T: 'static,
diff --git a/crates/wasmtime/src/runtime/memory.rs b/crates/wasmtime/src/runtime/memory.rs
index 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.rs
index 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.rs
index 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.rs
index 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>,