Soup up documentation for errors and traps

crates/wasmtime/src/config.rs

@@ -381,15 +381,30 @@ impl Config {
  self
  }
 
- /// Configures whether backtraces exist in a `Trap`.
- ///
- /// Enabled by default, this feature builds in support to
- /// generate backtraces at runtime for WebAssembly modules. This means that
- /// unwinding information is compiled into wasm modules and necessary runtime
- /// dependencies are enabled as well.
- ///
- /// When disabled, wasm backtrace details are ignored, and [`crate::Trap::trace()`]
- /// will always return `None`.
+ /// Configures whether [`WasmBacktrace`] will be present in the context of
+ /// errors returned from Wasmtime.
+ ///
+ /// A backtrace may be collected whenever an error is returned from a host
+ /// function call through to WebAssembly or when WebAssembly itself hits a
+ /// trap condition, such as an out-of-bounds memory access. This flag
+ /// indicates, in these conditions, whether the backtrace is collected or
+ /// not.
+ ///
+ /// Currently wasm backtraces are implemented through frame pointer walking.
+ /// This means that collecting a backtrace is expected to be a fast and
+ /// relatively cheap operation. Additionally backtrace collection is
+ /// suitable in concurrent environments since one thread capturing a
+ /// backtrace won't block other threads.
+ ///
+ /// Collected backtraces are attached via [`anyhow::Error::context`] to
+ /// errors returned from host functions. The [`WasmBacktrace`] type can be
+ /// acquired via [`anyhow::Error::downcast_ref`] to inspect the backtrace.
+ /// When this option is disabled then this context is never applied to
+ /// errors coming out of wasm.
+ ///
+ /// This option is `true` by default.
+ ///
+ /// [`WasmBacktrace`]: crate::WasmBacktrace
  #[deprecated = "Backtraces will always be enabled in future Wasmtime releases; if this \
  causes problems for you, please file an issue."]
  pub fn wasm_backtrace(&mut self, enable: bool) -> &mut Self {
@@ -429,13 +444,16 @@ impl Config {
  /// This configuration option only exists to help third-party stack
  /// capturing mechanisms, such as the system's unwinder or the `backtrace`
  /// crate, determine how to unwind through Wasm frames. It does not affect
- /// whether Wasmtime can capture Wasm backtraces or not, or whether
- /// [`Trap::trace`][crate::Trap::trace] returns `Some` or `None`.
+ /// whether Wasmtime can capture Wasm backtraces or not. The presence of
+ /// [`WasmBacktrace`] is controlled by the [`Config::wasm_backtrace`]
+ /// option.
  ///
  /// Note that native unwind information is always generated when targeting
  /// Windows, since the Windows ABI requires it.
  ///
  /// This option defaults to `true`.
+ ///
+ /// [`WasmBacktrace`]: crate::WasmBacktrace
  pub fn native_unwind_info(&mut self, enable: bool) -> &mut Self {
  self.native_unwind_info = enable;
  self

crates/wasmtime/src/func.rs

@@ -327,6 +327,22 @@ impl Func {
  ///
  /// For more information about `Send + Sync + 'static` requirements on the
  /// `func`, see [`Func::wrap`](#why-send--sync--static).
+ ///
+ /// # Errors
+ ///
+ /// The host-provided function here returns a
+ /// [`Result<()>`](anyhow::Result). If the function returns `Ok(())` then
+ /// that indicates that the host function completed successfully and wrote
+ /// the result into the `&mut [Val]` argument.
+ ///
+ /// If the function returns `Err(e)`, however, then this is equivalent to
+ /// the host function triggering a trap for wasm. WebAssembly execution is
+ /// immediately halted and the original caller of [`Func::call`], for
+ /// example, will receive the error returned here (possibly with
+ /// [`WasmBacktrace`](crate::WasmBacktrace) context information attached).
+ ///
+ /// For more information about errors in Wasmtime see the [`Trap`]
+ /// documentation.
  #[cfg(compiler)]
  #[cfg_attr(nightlydoc, doc(cfg(feature = "cranelift")))] // see build.rs
  pub fn new<T>(
@@ -355,6 +371,11 @@ impl Func {
  /// [`Func::new`] or [`Func::wrap`]. The [`Func::wrap`] API, in particular,
  /// is both safer and faster than this API.
  ///
+ /// # Errors
+ ///
+ /// See [`Func::new`] for the behavior of returning an error from the host
+ /// function provided here.
+ ///
  /// # Unsafety
  ///
  /// This function is not safe because it's not known at compile time that
@@ -392,6 +413,11 @@ impl Func {
  /// This function will panic if `store` is not associated with an [async
  /// config](crate::Config::async_support).
  ///
+ /// # Errors
+ ///
+ /// See [`Func::new`] for the behavior of returning an error from the host
+ /// function provided here.
+ ///
  /// # Examples
  ///
  /// ```
@@ -543,6 +569,18 @@ impl Func {
  /// actually closing over any values. These zero-sized types will use the
  /// context from [`Caller`] for host-defined information.
  ///
+ /// # Errors
+ ///
+ /// The closure provided here to `wrap` can optionally return a
+ /// [`Result<T>`](anyhow::Result). Returning `Ok(t)` represents the host
+ /// function successfully completing with the `t` result. Returning
+ /// `Err(e)`, however, is equivalent to raising a custom wasm trap.
+ /// Execution of WebAssembly does not resume and the stack is unwound to the
+ /// original caller of the function where the error is returned.
+ ///
+ /// For more information about errors in Wasmtime see the [`Trap`]
+ /// documentation.
+ ///
  /// # Examples
  ///
  /// First up we can see how simple wasm imports can be implemented, such
@@ -750,16 +788,41 @@ impl Func {
  /// Invokes this function with the `params` given and writes returned values
  /// to `results`.
  ///
- /// The `params` here must match the type signature of this `Func`, or a
- /// trap will occur. If a trap occurs while executing this function, then a
- /// trap will also be returned. Additionally `results` must have the same
- /// length as the number of results for this function.
+ /// The `params` here must match the type signature of this `Func`, or an
+ /// error will occur. Additionally `results` must have the same
+ /// length as the number of results for this function. Calling this function
+ /// will synchronously execute the WebAssembly function referenced to get
+ /// the results.
+ ///
+ /// This function will return `Ok(())` if execution completed without a trap
+ /// or error of any kind. In this situation the results will be written to
+ /// the provided `results` array.
+ ///
+ /// # Errors
+ ///
+ /// Any error which occurs throughout the execution of the function will be
+ /// returned as `Err(e)`. The [`Error`](anyhow::Error) type can be inspected
+ /// for the precise error cause such as:
+ ///
+ /// * [`Trap`] - indicates that a wasm trap happened and execution was
+ /// halted.
+ /// * [`WasmBacktrace`] - optionally included on errors for backtrace
+ /// information of the trap/error.
+ /// * Other string-based errors to indicate issues such as type errors with
+ /// `params`.
+ /// * Any host-originating error originally returned from a function defined
+ /// via [`Func::new`], for example.
+ ///
+ /// Errors typically indicate that execution of WebAssembly was halted
+ /// mid-way and did not complete after the error condition happened.
  ///
  /// # Panics
  ///
  /// This function will panic if called on a function belonging to an async
  /// store. Asynchronous stores must always use `call_async`.
  /// initiates a panic. Also panics if `store` does not own this function.
+ ///
+ /// [`WasmBacktrace`]: crate::WasmBacktrace
  pub fn call(
  &self,
  mut store: impl AsContextMut,
@@ -788,6 +851,10 @@ impl Func {
  /// invoked many times with new `ExternRef` values and no other GC happens
  /// via any other means then no values will get collected.
  ///
+ /// # Errors
+ ///
+ /// For more information about errors see the [`Func::call`] documentation.
+ ///
  /// # Unsafety
  ///
  /// This function is unsafe because the `params_and_returns` argument is not
@@ -878,6 +945,10 @@ impl Func {
  /// For more information see the documentation on [asynchronous
  /// configs](crate::Config::async_support).
  ///
+ /// # Errors
+ ///
+ /// For more information on errors see the [`Func::call`] documentation.
+ ///
  /// # Panics
  ///
  /// Panics if this is called on a function in a synchronous store. This

crates/wasmtime/src/func/typed.rs

@@ -68,6 +68,10 @@ where
  /// For more information, see the [`Func::typed`] and [`Func::call`]
  /// documentation.
  ///
+ /// # Errors
+ ///
+ /// For more information on errors see the documentation on [`Func::call`].
+ ///
  /// # Panics
  ///
  /// This function will panic if it is called when the underlying [`Func`] is
@@ -91,6 +95,10 @@ where
  /// For more information, see the [`Func::typed`] and [`Func::call_async`]
  /// documentation.
  ///
+ /// # Errors
+ ///
+ /// For more information on errors see the documentation on [`Func::call`].
+ ///
  /// # Panics
  ///
  /// This function will panic if it is called when the underlying [`Func`] is

crates/wasmtime/src/instance.rs

@@ -88,7 +88,8 @@ impl Instance {
  ///
  /// When instantiation fails it's recommended to inspect the return value to
  /// see why it failed, or bubble it upwards. If you'd like to specifically
- /// check for trap errors, you can use `error.downcast::<Trap>()`.
+ /// check for trap errors, you can use `error.downcast::<Trap>()`. For more
+ /// about error handling see the [`Trap`] documentation.
  ///
  /// # Panics
  ///
@@ -102,7 +103,7 @@ impl Instance {
  mut store: impl AsContextMut,
  module: &Module,
  imports: &[Extern],
- ) -> Result<Instance, Error> {
+ ) -> Result<Instance> {
  let mut store = store.as_context_mut();
  let imports = Instance::typecheck_externs(store.0, module, imports)?;
  // Note that the unsafety here should be satisfied by the call to
@@ -134,7 +135,7 @@ impl Instance {
  mut store: impl AsContextMut<Data = T>,
  module: &Module,
  imports: &[Extern],
- ) -> Result<Instance, Error>
+ ) -> Result<Instance>
  where
  T: Send,
  {