First iteration on documentation.

This commit is contained in:
Sergey Pepyakin 2018-01-23 19:38:49 +03:00
parent 55342dceaf
commit 41983cff0a
6 changed files with 89 additions and 6 deletions

View File

@ -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<FuncInstance>);
@ -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)]

View File

@ -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<GlobalInstance>);
@ -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<RuntimeValue>,

View File

@ -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]);

View File

@ -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<MemoryInstance>);
@ -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,

View File

@ -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<TableInstance>);
@ -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,

View File

@ -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<ValueType>,
return_type: Option<ValueType>,
@ -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 twos complement representation.
///
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub enum ValueType {
I32,