wasmtime_runtime/
lib.rs

1//! Runtime library support for Wasmtime.
2
3#![deny(missing_docs, trivial_numeric_casts, unused_extern_crates)]
4#![warn(unused_import_braces)]
5#![cfg_attr(feature = "clippy", plugin(clippy(conf_file = "../../clippy.toml")))]
6#![cfg_attr(
7    feature = "cargo-clippy",
8    allow(clippy::new_without_default, clippy::new_without_default)
9)]
10#![cfg_attr(
11    feature = "cargo-clippy",
12    warn(
13        clippy::float_arithmetic,
14        clippy::mut_mut,
15        clippy::nonminimal_bool,
16        clippy::map_unwrap_or,
17        clippy::clippy::print_stdout,
18        clippy::unicode_not_nfc,
19        clippy::use_self
20    )
21)]
22
23use anyhow::Error;
24use std::fmt;
25use std::sync::atomic::{AtomicU64, AtomicUsize, Ordering};
26use std::sync::Arc;
27use wasmtime_environ::{DefinedFuncIndex, DefinedMemoryIndex, HostPtr, VMOffsets};
28
29#[macro_use]
30mod trampolines;
31
32#[cfg(feature = "component-model")]
33pub mod component;
34mod export;
35mod externref;
36mod imports;
37mod instance;
38mod memory;
39mod mmap;
40mod mmap_vec;
41mod parking_spot;
42mod table;
43mod traphandlers;
44mod vmcontext;
45
46pub mod debug_builtins;
47pub mod libcalls;
48
49pub use wasmtime_jit_debug::gdb_jit_int::GdbJitImageRegistration;
50
51pub use crate::export::*;
52pub use crate::externref::*;
53pub use crate::imports::Imports;
54pub use crate::instance::{
55    InstanceAllocationRequest, InstanceAllocator, InstanceHandle, OnDemandInstanceAllocator,
56    StorePtr,
57};
58#[cfg(feature = "pooling-allocator")]
59pub use crate::instance::{
60    InstanceLimits, PoolingInstanceAllocator, PoolingInstanceAllocatorConfig,
61};
62pub use crate::memory::{
63    DefaultMemoryCreator, Memory, RuntimeLinearMemory, RuntimeMemoryCreator, SharedMemory,
64};
65pub use crate::mmap::Mmap;
66pub use crate::mmap_vec::MmapVec;
67pub use crate::table::{Table, TableElement};
68pub use crate::trampolines::prepare_host_to_wasm_trampoline;
69pub use crate::traphandlers::{
70    catch_traps, init_traps, raise_lib_trap, raise_user_trap, resume_panic, tls_eager_initialize,
71    Backtrace, SignalHandler, TlsRestore, Trap, TrapReason,
72};
73pub use crate::vmcontext::{
74    VMCallerCheckedFuncRef, VMContext, VMFunctionBody, VMFunctionImport, VMGlobalDefinition,
75    VMGlobalImport, VMHostFuncContext, VMInvokeArgument, VMMemoryDefinition, VMMemoryImport,
76    VMOpaqueContext, VMRuntimeLimits, VMSharedSignatureIndex, VMTableDefinition, VMTableImport,
77    VMTrampoline, ValRaw,
78};
79
80mod module_id;
81pub use module_id::{CompiledModuleId, CompiledModuleIdAllocator};
82
83mod cow;
84pub use crate::cow::{MemoryImage, MemoryImageSlot, ModuleMemoryImages};
85
86/// Version number of this crate.
87pub const VERSION: &str = env!("CARGO_PKG_VERSION");
88
89/// Dynamic runtime functionality needed by this crate throughout the execution
90/// of a wasm instance.
91///
92/// This trait is used to store a raw pointer trait object within each
93/// `VMContext`. This raw pointer trait object points back to the
94/// `wasmtime::Store` internally but is type-erased so this `wasmtime_runtime`
95/// crate doesn't need the entire `wasmtime` crate to build.
96///
97/// Note that this is an extra-unsafe trait because no heed is paid to the
98/// lifetime of this store or the Send/Sync-ness of this store. All of that must
99/// be respected by embedders (e.g. the `wasmtime::Store` structure). The theory
100/// is that `wasmtime::Store` handles all this correctly.
101pub unsafe trait Store {
102    /// Returns the raw pointer in memory where this store's shared
103    /// `VMRuntimeLimits` structure is located.
104    ///
105    /// Used to configure `VMContext` initialization and store the right pointer
106    /// in the `VMContext`.
107    fn vmruntime_limits(&self) -> *mut VMRuntimeLimits;
108
109    /// Returns a pointer to the global epoch counter.
110    ///
111    /// Used to configure the `VMContext` on initialization.
112    fn epoch_ptr(&self) -> *const AtomicU64;
113
114    /// Returns the externref management structures necessary for this store.
115    ///
116    /// The first element returned is the table in which externrefs are stored
117    /// throughout wasm execution, and the second element is how to look up
118    /// module information for gc requests.
119    fn externref_activations_table(
120        &mut self,
121    ) -> (&mut VMExternRefActivationsTable, &dyn ModuleInfoLookup);
122
123    /// Callback invoked to allow the store's resource limiter to reject a
124    /// memory grow operation.
125    fn memory_growing(
126        &mut self,
127        current: usize,
128        desired: usize,
129        maximum: Option<usize>,
130    ) -> Result<bool, Error>;
131    /// Callback invoked to notify the store's resource limiter that a memory
132    /// grow operation has failed.
133    fn memory_grow_failed(&mut self, error: &Error);
134    /// Callback invoked to allow the store's resource limiter to reject a
135    /// table grow operation.
136    fn table_growing(
137        &mut self,
138        current: u32,
139        desired: u32,
140        maximum: Option<u32>,
141    ) -> Result<bool, Error>;
142    /// Callback invoked to notify the store's resource limiter that a table
143    /// grow operation has failed.
144    fn table_grow_failed(&mut self, error: &Error);
145    /// Callback invoked whenever fuel runs out by a wasm instance. If an error
146    /// is returned that's raised as a trap. Otherwise wasm execution will
147    /// continue as normal.
148    fn out_of_gas(&mut self) -> Result<(), Error>;
149    /// Callback invoked whenever an instance observes a new epoch
150    /// number. Cannot fail; cooperative epoch-based yielding is
151    /// completely semantically transparent. Returns the new deadline.
152    fn new_epoch(&mut self) -> Result<u64, Error>;
153}
154
155/// Functionality required by this crate for a particular module. This
156/// is chiefly needed for lazy initialization of various bits of
157/// instance state.
158///
159/// When an instance is created, it holds an `Arc<dyn ModuleRuntimeInfo>`
160/// so that it can get to signatures, metadata on functions, memory and
161/// funcref-table images, etc. All of these things are ordinarily known
162/// by the higher-level layers of Wasmtime. Specifically, the main
163/// implementation of this trait is provided by
164/// `wasmtime::module::ModuleInner`.  Since the runtime crate sits at
165/// the bottom of the dependence DAG though, we don't know or care about
166/// that; we just need some implementor of this trait for each
167/// allocation request.
168pub trait ModuleRuntimeInfo: Send + Sync + 'static {
169    /// The underlying Module.
170    fn module(&self) -> &Arc<wasmtime_environ::Module>;
171
172    /// Returns the address, in memory, that the function `index` resides at.
173    fn function(&self, index: DefinedFuncIndex) -> *mut VMFunctionBody;
174
175    /// Returns the `MemoryImage` structure used for copy-on-write
176    /// initialization of the memory, if it's applicable.
177    fn memory_image(&self, memory: DefinedMemoryIndex)
178        -> anyhow::Result<Option<&Arc<MemoryImage>>>;
179
180    /// A unique ID for this particular module. This can be used to
181    /// allow for fastpaths to optimize a "re-instantiate the same
182    /// module again" case.
183    fn unique_id(&self) -> Option<CompiledModuleId>;
184
185    /// A slice pointing to all data that is referenced by this instance.
186    fn wasm_data(&self) -> &[u8];
187
188    /// Returns an array, indexed by `SignatureIndex` of all
189    /// `VMSharedSignatureIndex` entries corresponding to the `SignatureIndex`.
190    fn signature_ids(&self) -> &[VMSharedSignatureIndex];
191
192    /// Offset information for the current host.
193    fn offsets(&self) -> &VMOffsets<HostPtr>;
194}
195
196/// Returns the host OS page size, in bytes.
197pub fn page_size() -> usize {
198    static PAGE_SIZE: AtomicUsize = AtomicUsize::new(0);
199
200    return match PAGE_SIZE.load(Ordering::Relaxed) {
201        0 => {
202            let size = get_page_size();
203            assert!(size != 0);
204            PAGE_SIZE.store(size, Ordering::Relaxed);
205            size
206        }
207        n => n,
208    };
209
210    #[cfg(windows)]
211    fn get_page_size() -> usize {
212        use std::mem::MaybeUninit;
213        use windows_sys::Win32::System::SystemInformation::*;
214
215        unsafe {
216            let mut info = MaybeUninit::uninit();
217            GetSystemInfo(info.as_mut_ptr());
218            info.assume_init_ref().dwPageSize as usize
219        }
220    }
221
222    #[cfg(unix)]
223    fn get_page_size() -> usize {
224        unsafe { libc::sysconf(libc::_SC_PAGESIZE) as usize }
225    }
226}
227
228/// Result of [`Memory::atomic_wait32`] and [`Memory::atomic_wait64`]
229#[derive(Copy, Clone, PartialEq, Eq, Debug)]
230pub enum WaitResult {
231    /// Indicates that a `wait` completed by being awoken by a different thread.
232    /// This means the thread went to sleep and didn't time out.
233    Ok = 0,
234    /// Indicates that `wait` did not complete and instead returned due to the
235    /// value in memory not matching the expected value.
236    Mismatch = 1,
237    /// Indicates that `wait` completed with a timeout, meaning that the
238    /// original value matched as expected but nothing ever called `notify`.
239    TimedOut = 2,
240}
241
242/// Description about a fault that occurred in WebAssembly.
243#[derive(Debug)]
244pub struct WasmFault {
245    /// The size of memory, in bytes, at the time of the fault.
246    pub memory_size: usize,
247    /// The WebAssembly address at which the fault occurred.
248    pub wasm_address: u64,
249}
250
251impl fmt::Display for WasmFault {
252    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
253        write!(
254            f,
255            "memory fault at wasm address 0x{:x} in linear memory of size 0x{:x}",
256            self.wasm_address, self.memory_size,
257        )
258    }
259}
wasmtime_runtime/lib.rs

wasmtime_runtime/
lib.rs
