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;
}