1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406
//! # Wasmtime's embedding API
//!
//! Wasmtime is a WebAssembly engine for JIT-compiled or ahead-of-time compiled
//! WebAssembly modules and components. More information about the Wasmtime
//! project as a whole can be found [in the documentation
//! book](https://docs.wasmtime.dev) whereas this documentation mostly focuses
//! on the API reference of the `wasmtime` crate itself.
//!
//! This crate contains an API used to interact with [WebAssembly modules] or
//! [WebAssembly components]. For example you can compile WebAssembly, create
//! instances, call functions, etc. As an embedder of WebAssembly you can also
//! provide guests functionality from the host by creating host-defined
//! functions, memories, globals, etc, which can do things that WebAssembly
//! cannot (such as print to the screen).
//!
//! [WebAssembly modules]: https://webassembly.github.io/spec
//! [WebAssembly components]: https://component-model.bytecodealliance.org
//!
//! The `wasmtime` crate is designed to be safe, efficient, and ergonomic.
//! This enables executing WebAssembly without the embedder needing to use
//! `unsafe` code, meaning that you're guaranteed there is no undefined behavior
//! or segfaults in either the WebAssembly guest or the host itself.
//!
//! The `wasmtime` crate can roughly be thought of as being split into two
//! halves:
//!
//! * One half of the crate is similar to the [JS WebAssembly
//! API](https://developer.mozilla.org/en-US/docs/WebAssembly) as well as the
//! [proposed C API](https://github.com/webassembly/wasm-c-api) and is
//! intended for working with [WebAssembly modules]. This API resides in the
//! root of the `wasmtime` crate's namespace, for example
//! [`wasmtime::Module`](`Module`).
//!
//! * The second half of the crate is for use with the [WebAssembly Component
//! Model]. The implementation of the component model is present in
//! [`wasmtime::component`](`component`) and roughly mirrors the structure for
//! core WebAssembly, for example [`component::Func`] mirrors [`Func`].
//!
//! [WebAssembly Component Model]: https://component-model.bytecodealliance.org
//!
//! An example of using Wasmtime to run a core WebAssembly module looks like:
//!
//! ```
//! use wasmtime::*;
//!
//! fn main() -> wasmtime::Result<()> {
//! let engine = Engine::default();
//!
//! // Modules can be compiled through either the text or binary format
//! let wat = r#"
//! (module
//! (import "host" "host_func" (func $host_hello (param i32)))
//!
//! (func (export "hello")
//! i32.const 3
//! call $host_hello)
//! )
//! "#;
//! let module = Module::new(&engine, wat)?;
//!
//! // Host functionality can be arbitrary Rust functions and is provided
//! // to guests through a `Linker`.
//! let mut linker = Linker::new(&engine);
//! linker.func_wrap("host", "host_func", |caller: Caller<'_, u32>, param: i32| {
//! println!("Got {} from WebAssembly", param);
//! println!("my host state is: {}", caller.data());
//! })?;
//!
//! // All wasm objects operate within the context of a "store". Each
//! // `Store` has a type parameter to store host-specific data, which in
//! // this case we're using `4` for.
//! let mut store: Store<u32> = Store::new(&engine, 4);
//!
//! // Instantiation of a module requires specifying its imports and then
//! // afterwards we can fetch exports by name, as well as asserting the
//! // type signature of the function with `get_typed_func`.
//! let instance = linker.instantiate(&mut store, &module)?;
//! let hello = instance.get_typed_func::<(), ()>(&mut store, "hello")?;
//!
//! // And finally we can call the wasm!
//! hello.call(&mut store, ())?;
//!
//! Ok(())
//! }
//! ```
//!
//! ## Core Concepts
//!
//! There are a number of core types and concepts that are important to be aware
//! of when using the `wasmtime` crate:
//!
//! * [`Engine`] - a global compilation and runtime environment for WebAssembly.
//! An [`Engine`] is an object that can be shared concurrently across threads
//! and is created with a [`Config`] with many knobs for configuring
//! behavior. Compiling or executing any WebAssembly requires first
//! configuring and creating an [`Engine`]. All [`Module`]s and
//! [`Component`](component::Component)s belong to an [`Engine`], and
//! typically there's one [`Engine`] per process.
//!
//! * [`Store`] - container for all information related to WebAssembly objects
//! such as functions, instances, memories, etc. A [`Store<T>`][`Store`]
//! allows customization of the `T` to store arbitrary host data within a
//! [`Store`]. This host data can be accessed through host functions via the
//! [`Caller`] function parameter in host-defined functions. A [`Store`] is
//! required for all WebAssembly operations, such as calling a wasm function.
//! The [`Store`] is passed in as a "context" to methods like [`Func::call`].
//! Dropping a [`Store`] will deallocate all memory associated with
//! WebAssembly objects within the [`Store`]. A [`Store`] is cheap to create
//! and destroy and does not GC objects such as unused instances internally,
//! so it's intended to be short-lived (or no longer than the instances it
//! contains).
//!
//! * [`Linker`] (or [`component::Linker`]) - host functions are defined within
//! a linker to provide them a string-based name which can be looked up when
//! instantiating a WebAssembly module or component. Linkers are traditionally
//! populated at startup and then reused for all future instantiations of all
//! instances, assuming the set of host functions does not change over time.
//! Host functions are `Fn(..) + Send + Sync` and typically do not close over
//! mutable state. Instead it's recommended to store mutable state in the `T`
//! of [`Store<T>`] which is accessed through [`Caller<'_,
//! T>`](crate::Caller) provided to host functions.
//!
//! * [`Module`] (or [`Component`](component::Component)) - a compiled
//! WebAssembly module or component. These structures contain compiled
//! executable code from a WebAssembly binary which is ready to execute after
//! being instantiated. These are expensive to create as they require
//! compilation of the input WebAssembly. Modules and components are safe to
//! share across threads, however. Modules and components can additionally be
//! [serialized into a list of bytes](crate::Module::serialize) to later be
//! [deserialized](crate::Module::deserialize) quickly. This enables JIT-style
//! compilation through constructors such as [`Module::new`] and AOT-style
//! compilation by having the compilation process use [`Module::serialize`]
//! and the execution process use [`Module::deserialize`].
//!
//! * [`Instance`] (or [`component::Instance`]) - an instantiated WebAssembly
//! module or component. An instance is where you can actually acquire a
//! [`Func`] (or [`component::Func`]) from, for example, to call.
//!
//! * [`Func`] (or [`component::Func`]) - a WebAssembly function. This can be
//! acquired as the export of an [`Instance`] to call WebAssembly functions,
//! or it can be created via functions like [`Func::wrap`] to wrap
//! host-defined functionality and give it to WebAssembly. Functions also have
//! typed views as [`TypedFunc`] or [`component::TypedFunc`] for a more
//! efficient calling convention.
//!
//! * [`Table`], [`Global`], [`Memory`], [`component::Resource`] - other
//! WebAssembly objects which can either be defined on the host or in wasm
//! itself (via instances). These all have various ways of being interacted
//! with like [`Func`].
//!
//! All "store-connected" types such as [`Func`], [`Memory`], etc, require the
//! store to be passed in as a context to each method. Methods in wasmtime
//! frequently have their first parameter as either [`impl
//! AsContext`][`AsContext`] or [`impl AsContextMut`][`AsContextMut`]. These
//! traits are implemented for a variety of types, allowing you to, for example,
//! pass the following types into methods:
//!
//! * `&Store<T>`
//! * `&mut Store<T>`
//! * `&Caller<'_, T>`
//! * `&mut Caller<'_, T>`
//! * `StoreContext<'_, T>`
//! * `StoreContextMut<'_, T>`
//!
//! A [`Store`] is the sole owner of all WebAssembly internals. Types like
//! [`Func`] point within the [`Store`] and require the [`Store`] to be provided
//! to actually access the internals of the WebAssembly function, for instance.
//!
//! ## WASI
//!
//! The `wasmtime` crate does not natively provide support for WASI, but you can
//! use the [`wasmtime-wasi`] crate for that purpose. With [`wasmtime-wasi`] all
//! WASI functions can be added to a [`Linker`] and then used to instantiate
//! WASI-using modules. For more information see the [WASI example in the
//! documentation](https://docs.wasmtime.dev/examples-rust-wasi.html).
//!
//! [`wasmtime-wasi`]: https://crates.io/crates/wasmtime-wasi
//!
//! ## Crate Features
//!
//! The `wasmtime` crate comes with a number of compile-time features that can
//! be used to customize what features it supports. Some of these features are
//! just internal details, but some affect the public API of the `wasmtime`
//! crate. Wasmtime APIs gated behind a Cargo feature should be indicated as
//! such in the documentation.
//!
//! * `runtime` - Enabled by default, this feature enables executing
//! WebAssembly modules and components. If a compiler is not available (such
//! as `cranelift`) then [`Module::deserialize`] must be used, for example, to
//! provide an ahead-of-time compiled artifact to execute WebAssembly.
//!
//! * `cranelift` - Enabled by default, this features enables using Cranelift at
//! runtime to compile a WebAssembly module to native code. This feature is
//! required to process and compile new WebAssembly modules and components.
//!
//! * `cache` - Enabled by default, this feature adds support for wasmtime to
//! perform internal caching of modules in a global location. This must still
//! be enabled explicitly through [`Config::cache_config_load`] or
//! [`Config::cache_config_load_default`].
//!
//! * `wat` - Enabled by default, this feature adds support for accepting the
//! text format of WebAssembly in [`Module::new`] and
//! [`Component::new`](component::Component::new). The text format will be
//! automatically recognized and translated to binary when compiling a
//! module.
//!
//! * `parallel-compilation` - Enabled by default, this feature enables support
//! for compiling functions in parallel with `rayon`.
//!
//! * `async` - Enabled by default, this feature enables APIs and runtime
//! support for defining asynchronous host functions and calling WebAssembly
//! asynchronously. For more information see [`Config::async_support`].
//!
//! * `profiling` - Enabled by default, this feature compiles in support for
//! profiling guest code via a number of possible strategies. See
//! [`Config::profiler`] for more information.
//!
//! * `all-arch` - Not enabled by default. This feature compiles in support for
//! all architectures for both the JIT compiler and the `wasmtime compile` CLI
//! command. This can be combined with [`Config::target`] to precompile
//! modules for a different platform than the host.
//!
//! * `pooling-allocator` - Enabled by default, this feature adds support for
//! [`PoolingAllocationConfig`] to pass to [`Config::allocation_strategy`].
//! The pooling allocator can enable efficient reuse of resources for
//! high-concurrency and high-instantiation-count scenarios.
//!
//! * `demangle` - Enabled by default, this will affect how backtraces are
//! printed and whether symbol names from WebAssembly are attempted to be
//! demangled. Rust and C++ demanglings are currently supported.
//!
//! * `coredump` - Enabled by default, this will provide support for generating
//! a core dump when a trap happens. This can be configured via
//! [`Config::coredump_on_trap`].
//!
//! * `addr2line` - Enabled by default, this feature configures whether traps
//! will attempt to parse DWARF debug information and convert WebAssembly
//! addresses to source filenames and line numbers.
//!
//! * `debug-builtins` - Enabled by default, this feature includes some built-in
//! debugging utilities and symbols for native debuggers such as GDB and LLDB
//! to attach to the process Wasmtime is used within. The intrinsics provided
//! will enable debugging guest code compiled to WebAssembly. This must also
//! be enabled via [`Config::debug_info`] as well for guests.
//!
//! * `component-model` - Enabled by default, this enables support for the
//! [`wasmtime::component`](component) API for working with components.
//!
//! * `gc` - Enabled by default, this enables support for a number of
//! WebAssembly proposals such as `reference-types`, `function-references`,
//! and `gc`. Note that the implementation of the `gc` proposal itself is not
//! yet complete at this time.
//!
//! * `threads` - Enabled by default, this enables compile-time support for the
//! WebAssembly `threads` proposal, notably shared memories.
//!
//! * `call-hook` - Disabled by default, this enables support for the
//! [`Store::call_hook`] API. This incurs a small overhead on all
//! entries/exits from WebAssembly and may want to be disabled by some
//! embedders.
//!
//! * `memory-protection-keys` - Disabled by default, this enables support for
//! the [`PoolingAllocationConfig::memory_protection_keys`] API. This feature
//! currently only works on x64 Linux and can enable compacting the virtual
//! memory allocation for linear memories in the pooling allocator. This comes
//! with the same overhead as the `call-hook` feature where entries/exits into
//! WebAssembly will have more overhead than before.
//!
//! More crate features can be found in the [manifest] of Wasmtime itself for
//! seeing what can be enabled and disabled.
//!
//! [manifest]: https://github.com/bytecodealliance/wasmtime/blob/main/crates/wasmtime/Cargo.toml
#![deny(missing_docs)]
#![doc(test(attr(deny(warnings))))]
#![doc(test(attr(allow(dead_code, unused_variables, unused_mut))))]
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![cfg_attr(not(feature = "default"), allow(dead_code, unused_imports))]
// Allow broken links when the default features is disabled because most of our
// documentation is written for the "one build" of the `main` branch which has
// most features enabled. This will present warnings in stripped-down doc builds
// and will prevent the doc build from failing.
#![cfg_attr(feature = "default", warn(rustdoc::broken_intra_doc_links))]
#![no_std]
#[cfg(any(feature = "std", unix, windows))]
#[macro_use]
extern crate std;
extern crate alloc;
pub(crate) mod prelude {
pub use crate::{Error, Result};
pub use anyhow::{anyhow, bail, ensure, format_err, Context};
pub use wasmtime_environ::prelude::*;
}
/// A helper macro to safely map `MaybeUninit<T>` to `MaybeUninit<U>` where `U`
/// is a field projection within `T`.
///
/// This is intended to be invoked as:
///
/// ```ignore
/// struct MyType {
/// field: u32,
/// }
///
/// let initial: &mut MaybeUninit<MyType> = ...;
/// let field: &mut MaybeUninit<u32> = map_maybe_uninit!(initial.field);
/// ```
///
/// Note that array accesses are also supported:
///
/// ```ignore
///
/// let initial: &mut MaybeUninit<[u32; 2]> = ...;
/// let element: &mut MaybeUninit<u32> = map_maybe_uninit!(initial[1]);
/// ```
#[doc(hidden)]
#[macro_export]
macro_rules! map_maybe_uninit {
($maybe_uninit:ident $($field:tt)*) => ({
#[allow(unused_unsafe)]
{
unsafe {
use $crate::MaybeUninitExt;
let m: &mut core::mem::MaybeUninit<_> = $maybe_uninit;
// Note the usage of `addr_of_mut!` here which is an attempt to "stay
// safe" here where we never accidentally create `&mut T` where `T` is
// actually uninitialized, hopefully appeasing the Rust unsafe
// guidelines gods.
m.map(|p| core::ptr::addr_of_mut!((*p)$($field)*))
}
}
})
}
#[doc(hidden)]
pub trait MaybeUninitExt<T> {
/// Maps `MaybeUninit<T>` to `MaybeUninit<U>` using the closure provided.
///
/// Note that this is `unsafe` as there is no guarantee that `U` comes from
/// `T`.
unsafe fn map<U>(&mut self, f: impl FnOnce(*mut T) -> *mut U)
-> &mut core::mem::MaybeUninit<U>;
}
impl<T> MaybeUninitExt<T> for core::mem::MaybeUninit<T> {
unsafe fn map<U>(
&mut self,
f: impl FnOnce(*mut T) -> *mut U,
) -> &mut core::mem::MaybeUninit<U> {
let new_ptr = f(self.as_mut_ptr());
core::mem::transmute::<*mut U, &mut core::mem::MaybeUninit<U>>(new_ptr)
}
}
#[cfg(feature = "runtime")]
mod runtime;
#[cfg(feature = "runtime")]
pub use runtime::*;
#[cfg(any(feature = "cranelift", feature = "winch"))]
mod compile;
#[cfg(any(feature = "cranelift", feature = "winch"))]
pub use compile::{CodeBuilder, CodeHint};
mod config;
mod engine;
mod profiling_agent;
pub use crate::config::*;
pub use crate::engine::*;
#[cfg(feature = "std")]
mod sync_std;
#[cfg(feature = "std")]
use sync_std as sync;
#[cfg_attr(feature = "std", allow(dead_code))]
mod sync_nostd;
#[cfg(not(feature = "std"))]
use sync_nostd as sync;
/// A convenience wrapper for `Result<T, anyhow::Error>`.
///
/// This type can be used to interact with `wasmtimes`'s extensive use
/// of `anyhow::Error` while still not directly depending on `anyhow`.
///
/// This type alias is identical to `anyhow::Result`.
#[doc(no_inline)]
pub use anyhow::{Error, Result};
fn _assert_send_and_sync<T: Send + Sync>() {}
fn _assertions_lib() {
_assert_send_and_sync::<Engine>();
_assert_send_and_sync::<Config>();
}
#[cfg(feature = "runtime")]
#[doc(hidden)]
pub mod _internal {
// Exported just for the CLI.
pub use crate::runtime::vm::MmapVec;
}