From 41983cff0a8a9211f0a25745fbf3689ee6db1edd Mon Sep 17 00:00:00 2001 From: Sergey Pepyakin Date: Tue, 23 Jan 2018 19:38:49 +0300 Subject: [PATCH] First iteration on documentation. --- src/func.rs | 21 +++++++++++++++++++++ src/global.rs | 15 +++++++++++++++ src/host.rs | 4 ++-- src/memory.rs | 16 +++++++++++++++- src/table.rs | 20 +++++++++++++++++++- src/types.rs | 19 +++++++++++++++++-- 6 files changed, 89 insertions(+), 6 deletions(-) diff --git a/src/func.rs b/src/func.rs index 7370124..38bfaf8 100644 --- a/src/func.rs +++ b/src/func.rs @@ -11,6 +11,12 @@ use module::ModuleInstance; use common::stack::StackWithLimit; use common::{DEFAULT_FRAME_STACK_LIMIT, DEFAULT_VALUE_STACK_LIMIT}; +/// Reference to a [`FuncInstance`]. +/// +/// This reference has a reference-counting semantics. +/// +/// [`FuncInstance`]: struct.FuncInstance.html +/// #[derive(Clone, Debug)] pub struct FuncRef(Rc); @@ -21,6 +27,21 @@ impl ::std::ops::Deref for FuncRef { } } +/// Runtime representation of a function. +/// +/// Functions are the unit of orgianization of code in WebAssembly. Each function takes a sequence of values +/// as parameters and either optionally return a value or trap. +/// Functions can call other function (including itself, i.e recursively) and imported functions +/// (i.e defined in another module). +/// +/// Functions can be defined either: +/// +/// - by a wasm module, +/// - by the host environment and passed to a wasm module as an import. +/// See more in [`Externals`]. +/// +/// [`Externals`]: trait.Externals.html +/// pub struct FuncInstance(FuncInstanceInternal); #[derive(Clone)] diff --git a/src/global.rs b/src/global.rs index 064e642..1edd774 100644 --- a/src/global.rs +++ b/src/global.rs @@ -5,6 +5,12 @@ use Error; use types::ValueType; use parity_wasm::elements::{ValueType as EValueType}; +/// Reference to a [`GlobalInstance`]. +/// +/// This reference has a reference-counting semantics. +/// +/// [`GlobalInstance`]: struct.GlobalInstance.html +/// #[derive(Clone, Debug)] pub struct GlobalRef(Rc); @@ -15,6 +21,15 @@ impl ::std::ops::Deref for GlobalRef { } } +/// Runtime representation of a global variable (or `global` for short). +/// +/// Global contains a value of a specified type and flag which specifies whether this +/// global are mutable or immutable. Neither type of the value nor immutability can't be changed +/// after creation. +/// +/// Attempt to change value of immutable global or to change type of +/// the value (e.g. assign I32 value to a global that was created with I64 type) will lead to an error. +/// #[derive(Debug)] pub struct GlobalInstance { val: Cell, diff --git a/src/host.rs b/src/host.rs index 09b6c85..ff12f94 100644 --- a/src/host.rs +++ b/src/host.rs @@ -2,7 +2,7 @@ use std::any::TypeId; use value::{RuntimeValue, TryInto}; use Error; -/// Safe wrapper for list of arguments +/// Safe wrapper for list of arguments. #[derive(Debug)] pub struct RuntimeArgs<'a>(&'a [RuntimeValue]); @@ -100,4 +100,4 @@ mod tests { let args: RuntimeArgs = (&[RuntimeValue::I64(90534534545322)][..]).into(); assert!(args.nth::(0).is_err()); } -} \ No newline at end of file +} diff --git a/src/memory.rs b/src/memory.rs index 5cffc6c..52e0c08 100644 --- a/src/memory.rs +++ b/src/memory.rs @@ -13,6 +13,12 @@ pub const LINEAR_MEMORY_PAGE_SIZE: u32 = 65536; /// Maximal number of pages. const LINEAR_MEMORY_MAX_PAGES: u32 = 65536; +/// Reference to a [`MemoryInstance`]. +/// +/// This reference has a reference-counting semantics. +/// +/// [`MemoryInstance`]: struct.MemoryInstance.html +/// #[derive(Clone, Debug)] pub struct MemoryRef(Rc); @@ -23,7 +29,15 @@ impl ::std::ops::Deref for MemoryRef { } } -/// Linear memory instance. +/// Runtime representation of a linear memory (or `memory` for short). +/// +/// A memory is a contiguous, mutable array of raw bytes. Wasm code can load and store values +/// from/to a linear memory at any byte address. +/// A trap occurs if an access is not within the bounds of the current memory size. +/// +/// A memory is created with an initial size but can be grown dynamically. +/// The growth can be limited by specifying maximum size. +/// The size of a memory is always a integer multiple of a page size - 64KiB. pub struct MemoryInstance { /// Memofy limits. limits: ResizableLimits, diff --git a/src/table.rs b/src/table.rs index 0f78f39..fb33da9 100644 --- a/src/table.rs +++ b/src/table.rs @@ -7,6 +7,12 @@ use Error; use func::FuncRef; use module::check_limits; +/// Reference to a [`TableInstance`]. +/// +/// This reference has a reference-counting semantics. +/// +/// [`TableInstance`]: struct.TableInstance.html +/// #[derive(Clone, Debug)] pub struct TableRef(Rc); @@ -17,7 +23,19 @@ impl ::std::ops::Deref for TableRef { } } -/// Table instance. +/// Runtime representation of a table. +/// +/// A table is a array of untyped functions. It allows wasm code to call functions +/// indirectly through a dynamic index into a table. For example, this allows emulating function +/// pointers by way of table indices. +/// +/// Table is created with an initial size but can be grown dynamically via [`grow`] method. +/// Growth can be limited by an optional maximum size. +/// +/// In future, a table might be extended to be able to hold not only functions but different types. +/// +/// [`grow`]: #method.grow +/// pub struct TableInstance { /// Table limits. limits: ResizableLimits, diff --git a/src/types.rs b/src/types.rs index 01c7c25..7191011 100644 --- a/src/types.rs +++ b/src/types.rs @@ -1,7 +1,14 @@ use parity_wasm::elements::{ FunctionType, ValueType as EValueType, GlobalType, TableType, MemoryType}; -#[derive(Debug, Clone, PartialEq)] +/// Signature of a function. +/// +/// Signature of a function consists of zero or more parameter [types][type] and zero or one return [type]. +/// +/// Two signatures are considered equal if they have equal list of parameters and equal return types. +/// +/// [type]: enum.ValueType.html +#[derive(Debug, Clone, PartialEq, Eq)] pub struct Signature { params: Vec, return_type: Option, @@ -31,6 +38,14 @@ impl Signature { } } +/// Type of a value. +/// +/// Wasm code manipulate values of the four basic value types: +/// integers and floating-point (IEEE 754-2008) data of 32 or 64 bit width each, respectively. +/// +/// There is no distinction between signed and unsigned integer types. Instead, integers are +/// interpreted by respective operations as either unsigned or signed in two’s complement representation. +/// #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub enum ValueType { I32, @@ -122,5 +137,5 @@ impl MemoryDescriptor { pub fn maximum(&self) -> Option { self.maximum - } + } }