diff --git a/lib/api/src/externals/function.rs b/lib/api/src/externals/function.rs index 1df33f2cc..2cef32dd8 100644 --- a/lib/api/src/externals/function.rs +++ b/lib/api/src/externals/function.rs @@ -38,6 +38,14 @@ pub enum FunctionDefinition { } /// A WebAssembly `function`. +/// +/// A function instance is the runtime representation of a function. +/// It effectively is a closure of the original function over the runtime +/// `Instance` of its originating `Module`. The module instance is used +/// to resolve references to other definitions during execution of the +/// function. +/// +/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#function-instances #[derive(Clone, PartialEq)] pub struct Function { pub(crate) store: Store, @@ -46,7 +54,7 @@ pub struct Function { } impl Function { - /// Creates a new `Function` that is: + /// Creates a new host `Function` that is: /// /// 1. Static/Monomorphic, i.e. all inputs and outputs have a /// unique _statically declared type_. The outputs can be @@ -77,7 +85,7 @@ impl Function { } } - /// Creates a new `Function` that is: + /// Creates a new host `Function` that is: /// /// 1. Static/Monomorphic, i.e. all inputs and outputs have a /// unique statically declared type. The outputs can be wrapped @@ -115,7 +123,7 @@ impl Function { } } - /// Creates a new `Function` that is: + /// Creates a new host `Function` that is: /// /// 1. Dynamic/Polymorphic, i.e. all inputs are received in a /// slice of `Val` (the set of all Wasm values), and all @@ -150,7 +158,7 @@ impl Function { } } - /// Creates a new `Function` that is: + /// Creates a new host `Function` that is: /// /// 1. Dynamic/Polymorphic, i.e. all inputs are received in a /// slice of `Val` (the set of all Wasm values), and all @@ -187,11 +195,12 @@ impl Function { } } - /// Returns the underlying type of this function. + /// Returns the underlying [`FunctionType`] corresponding to this runtime `Function`. pub fn ty(&self) -> &FunctionType { &self.exported.signature } + /// Returns the [`Store`] that owns this `Function`. pub fn store(&self) -> &Store { &self.store } diff --git a/lib/api/src/externals/global.rs b/lib/api/src/externals/global.rs index 275bc40c1..f22de723e 100644 --- a/lib/api/src/externals/global.rs +++ b/lib/api/src/externals/global.rs @@ -8,6 +8,12 @@ use crate::RuntimeError; use std::fmt; use wasmer_vm::{Export, ExportGlobal, VMGlobalDefinition}; +/// A WebAssembly `global`. +/// +/// A global instance is the runtime representation of a global variable. +/// It holds an individual value and a flag indicating whether it is mutable. +/// +/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#global-instances #[derive(Clone)] pub struct Global { store: Store, @@ -15,12 +21,14 @@ pub struct Global { } impl Global { + /// Create a new `Global` with the initial value [`Val`]. pub fn new(store: &Store, val: Val) -> Global { // Note: we unwrap because the provided type should always match // the value type, so it's safe to unwrap. Self::from_type(store, GlobalType::new(val.ty(), Mutability::Const), val).unwrap() } + /// Create a mutable `Global` with the initial value [`Val`]. pub fn new_mut(store: &Store, val: Val) -> Global { // Note: we unwrap because the provided type should always match // the value type, so it's safe to unwrap. @@ -52,14 +60,17 @@ impl Global { }) } + /// Returns the underlying [`GlobalType`] corresponding to this runtime `Global`. pub fn ty(&self) -> &GlobalType { &self.exported.global } + /// Returns the [`Store`] that owns this `Global`. pub fn store(&self) -> &Store { &self.store } + /// Retrieves the current value [`Val`] that the Global has. pub fn get(&self) -> Val { unsafe { let definition = &mut *self.exported.definition; @@ -73,6 +84,13 @@ impl Global { } } + /// Sets a custom value [`Val`] to the runtime Global. + /// + /// # Errors + /// + /// This function will error if: + /// * The global is not mutable + /// * The type of the `Val` doesn't matches the Global type. pub fn set(&self, val: Val) -> Result<(), RuntimeError> { if self.ty().mutability != Mutability::Var { return Err(RuntimeError::new( diff --git a/lib/api/src/externals/memory.rs b/lib/api/src/externals/memory.rs index a42b719e4..ec53954dc 100644 --- a/lib/api/src/externals/memory.rs +++ b/lib/api/src/externals/memory.rs @@ -7,6 +7,17 @@ use std::sync::Arc; use wasm_common::{Pages, ValueType}; use wasmer_vm::{Export, ExportMemory, Memory as RuntimeMemory, MemoryError}; +/// A WebAssembly `memory`. +/// +/// A memory instance is the runtime representation of a linear memory. +/// It holds a vector of bytes and an optional maximum size. +/// +/// The length of the vector always is a multiple of the WebAssembly +/// page size, which is defined to be the constant 65536 – abbreviated 64Ki. +/// Like in a memory type, the maximum size in a memory instance is +/// given in units of this page size. +/// +/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#memory-instances #[derive(Clone)] pub struct Memory { store: Store, @@ -14,6 +25,9 @@ pub struct Memory { } impl Memory { + /// Creates a new host `Memory` from the provided [`MemoryType`]. + /// + /// This function will construct the `Memory` using the store [`Tunables`]. pub fn new(store: &Store, ty: MemoryType) -> Result { let tunables = store.tunables(); let style = tunables.memory_style(&ty); @@ -25,10 +39,12 @@ impl Memory { }) } + /// Returns the underlying [`MemoryType`] corresponding to this runtime `Memory`. pub fn ty(&self) -> &MemoryType { self.memory.ty() } + /// Returns the [`Store`] that owns this `Memory`. pub fn store(&self) -> &Store { &self.store } @@ -55,22 +71,31 @@ impl Memory { slice::from_raw_parts_mut(def.base, def.current_length) } + /// Returns the pointer to the `Memory`. pub fn data_ptr(&self) -> *mut u8 { let definition = self.memory.vmmemory(); let def = unsafe { definition.as_ref() }; def.base } + /// Returns the size (in bytes) of the `Memory`. pub fn data_size(&self) -> usize { let definition = self.memory.vmmemory(); let def = unsafe { definition.as_ref() }; def.current_length } + /// Returns the size (in [`Pages`]) of the `Memory`. pub fn size(&self) -> Pages { self.memory.size() } + /// Grow memory by the specified amount of WebAssembly [`Pages`]. + /// + /// # Errors + /// + /// Returns an error if memory can't be grown by the specified amount + /// of pages. pub fn grow(&self, delta: IntoPages) -> Result where IntoPages: Into, diff --git a/lib/api/src/externals/mod.rs b/lib/api/src/externals/mod.rs index f2405048d..87759246a 100644 --- a/lib/api/src/externals/mod.rs +++ b/lib/api/src/externals/mod.rs @@ -15,15 +15,24 @@ use crate::store::{Store, StoreObject}; use crate::ExternType; use wasmer_vm::Export; +/// An external value is the runtime representation of an entity that +/// can be imported or exported. +/// +/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#external-values #[derive(Clone)] pub enum Extern { + /// A external [`Function`] Function(Function), + /// A external [`Global`] Global(Global), + /// A external [`Table`] Table(Table), + /// A external [`Memory`] Memory(Memory), } impl Extern { + /// Return the undelying type of the inner `Extern`. pub fn ty(&self) -> ExternType { match self { Extern::Function(ft) => ExternType::Function(ft.ty().clone()), diff --git a/lib/api/src/externals/table.rs b/lib/api/src/externals/table.rs index f3c44c39d..1ed202f93 100644 --- a/lib/api/src/externals/table.rs +++ b/lib/api/src/externals/table.rs @@ -12,6 +12,8 @@ use wasmer_vm::{Export, ExportTable, Table as RuntimeTable, VMCallerCheckedAnyfu /// /// A table created by the host or in WebAssembly code will be accessible and /// mutable from both host and WebAssembly. +/// +/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#table-instances #[derive(Clone)] pub struct Table { store: Store, @@ -30,6 +32,8 @@ impl Table { /// Creates a new `Table` with the provided [`TableType`] definition. /// /// All the elements in the table will be set to the `init` value. + /// + /// This function will construct the `Table` using the store [`Tunables`]. pub fn new(store: &Store, ty: TableType, init: Val) -> Result { let item = init.into_checked_anyfunc(store)?; let tunables = store.tunables(); @@ -54,6 +58,7 @@ impl Table { self.table.ty() } + /// Returns the [`Store`] that owns this `Table`. pub fn store(&self) -> &Store { &self.store } diff --git a/lib/api/src/instance.rs b/lib/api/src/instance.rs index 9287f8bda..72e6aa383 100644 --- a/lib/api/src/instance.rs +++ b/lib/api/src/instance.rs @@ -12,6 +12,8 @@ use wasmer_vm::InstanceHandle; /// Instance objects contain all the exported WebAssembly /// functions, memories, tables and globals that allow /// interacting with WebAssembly. +/// +/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#module-instances #[derive(Clone)] pub struct Instance { handle: InstanceHandle, @@ -94,6 +96,7 @@ impl Instance { &self.module } + /// Returns the [`Store`] that owns this `Instance`. pub fn store(&self) -> &Store { self.module.store() } diff --git a/lib/api/src/lib.rs b/lib/api/src/lib.rs index 7b7274e37..636e425b6 100644 --- a/lib/api/src/lib.rs +++ b/lib/api/src/lib.rs @@ -1,5 +1,25 @@ //! Wasmer API -#![deny(intra_doc_link_resolution_failure)] +#![deny( + missing_docs, + trivial_numeric_casts, + unused_extern_crates, + intra_doc_link_resolution_failure +)] +#![warn(unused_import_braces)] +#![cfg_attr(feature = "cargo-clippy", allow(clippy::new_without_default))] +#![cfg_attr( + feature = "cargo-clippy", + warn( + clippy::float_arithmetic, + clippy::mut_mut, + clippy::nonminimal_bool, + clippy::option_map_unwrap_or, + clippy::option_map_unwrap_or_else, + clippy::print_stdout, + clippy::unicode_not_nfc, + clippy::use_self + ) +)] mod exports; mod externals; diff --git a/lib/api/src/module.rs b/lib/api/src/module.rs index e24dc5570..7af55567a 100644 --- a/lib/api/src/module.rs +++ b/lib/api/src/module.rs @@ -108,6 +108,7 @@ impl Module { Module::from_binary(store, bytes.as_ref()) } + /// Creates a new WebAssembly module from a file path. pub fn from_file(store: &Store, file: impl AsRef) -> Result { let file_ref = file.as_ref(); let canonical = file_ref.canonicalize()?; @@ -120,7 +121,7 @@ impl Module { Ok(module) } - /// Creates a new WebAssembly module from a binary. + /// Creates a new WebAssembly module from a binary. /// /// Opposed to [`Module::new`], this function is not compatible with /// the WebAssembly text format (if the "wat" feature is enabled for @@ -394,6 +395,7 @@ impl Module { self.artifact.module_ref().custom_sections(name) } + /// Returns the [`Store`] that owns this `Instance`. pub fn store(&self) -> &Store { &self.store } diff --git a/lib/api/src/native.rs b/lib/api/src/native.rs index 0de061c12..6cd3996cf 100644 --- a/lib/api/src/native.rs +++ b/lib/api/src/native.rs @@ -20,6 +20,8 @@ use wasmer_vm::{ ExportFunction, VMContext, VMDynamicFunctionContext, VMFunctionBody, VMFunctionKind, }; +/// A WebAssembly function that can be called natively +/// (using the Native ABI). pub struct NativeFunc<'a, Args = (), Rets = ()> { definition: FunctionDefinition, store: Store, diff --git a/lib/api/src/store.rs b/lib/api/src/store.rs index 84641f24c..7b6797c95 100644 --- a/lib/api/src/store.rs +++ b/lib/api/src/store.rs @@ -6,11 +6,16 @@ use wasmer_engine::Tunables as BaseTunables; use std::sync::Arc; use wasmer_engine::Engine; -/// The store is what holds the directives to the `wasmer` crate, and -/// siblings, to act as expected. It holds the engine (that is -/// —amongst many things— used to compile the Wasm bytes into a valid -/// module artifact), in addition to the tunables (that is used to -/// create the memories, tables and globals). +/// The store represents all global state that can be manipulated by +/// WebAssembly programs. It consists of the runtime representation +/// of all instances of functions, tables, memories, and globals that +/// have been allocated during the life time of the abstract machine. +/// +/// The `Store` holds the engine (that is —amongst many things— used to compile +/// the Wasm bytes into a valid module artifact), in addition to the +/// [`Tunables`] (that are used to create the memories, tables and globals). +/// +/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#store #[derive(Clone)] pub struct Store { engine: Arc, @@ -18,7 +23,7 @@ pub struct Store { } impl Store { - /// Creates a new `Store` with a specific `Engine`. + /// Creates a new `Store` with a specific [`Engine`]. pub fn new(engine: &E) -> Self where E: Engine + ?Sized, @@ -29,8 +34,7 @@ impl Store { } } - /// Creates a new `Store` with a specific `Engine` and a specific - /// `Tunables`. + /// Creates a new `Store` with a specific [`Engine`] and [`Tunables`]. pub fn new_with_tunables( engine: &E, tunables: impl BaseTunables + Send + Sync + 'static, @@ -44,12 +48,12 @@ impl Store { } } - /// Returns the tunables. + /// Returns the [`Tunables`]. pub fn tunables(&self) -> &dyn BaseTunables { self.tunables.as_ref() } - /// Returns the engine. + /// Returns the [`Engine`]. pub fn engine(&self) -> &Arc { &self.engine } @@ -115,6 +119,8 @@ impl Default for Store { } } +/// A trait represinting any object that lives in the `Store`. pub trait StoreObject { + /// Return true if the object `Store` is the same as the provided `Store`. fn comes_from_same_store(&self, store: &Store) -> bool; } diff --git a/lib/api/src/types.rs b/lib/api/src/types.rs index 044361871..c77a23de8 100644 --- a/lib/api/src/types.rs +++ b/lib/api/src/types.rs @@ -8,6 +8,11 @@ pub use wasm_common::{ MemoryType, Mutability, TableType, Type as ValType, }; +/// WebAssembly computations manipulate values of basic value types: +/// * Integers (32 or 64 bit width) +/// * Floating-point (32 or 64 bit width) +/// +/// Spec: https://webassembly.github.io/spec/core/exec/runtime.html#values pub type Val = Value; impl StoreObject for Val {