Document and update the API of the externals.rs module (#812)

* Document and update the API of the `externals.rs` module

This commit ensures that all public methods and items are documented in
the `externals.rs` module, notably all external values that can be
imported and exported in WebAssembly. Along the way this also tidies up
the API and fixes a few bugs:

* `Global::new` now returns a `Result` and fails if the provided value
  does not match the type of the global.
* `Global::set` now returns a `Result` and fails if the global is either
  immutable or the provided value doesn't match the type of the global.
* `Table::new` now fails if the provided initializer does not match the
  element type.
* `Table::get` now returns `Option<Val>` instead of implicitly returning
  null.
* `Table::set` now returns `Result<()>`, returning an error on out of
  bounds or if the input type is of the wrong type.
* `Table::grow` now returns `Result<u32>`, returning the previous number
  of table elements if succesful or an error if the maximum is reached
  or the initializer value is of the wrong type. Additionally a bug was
  fixed here where if the wrong initializer was provided the table would
  be grown still, but initialization would fail.
* `Memory::data` was renamed to `Memory::data_unchecked_mut`.
  Additionally `Memory::data_unchecked` was added. Lots of caveats were
  written down about how using the method can go wrong.
* `Memory::grow` now returns `Result<u32>`, returning an error if growth
  fails or the number of pages previous the growth if successful.

* Run rustfmt

* Fix another test

* Update crates/api/src/externals.rs

Co-Authored-By: Sergei Pepyakin <s.pepyakin@gmail.com>

Co-authored-by: Sergei Pepyakin <s.pepyakin@gmail.com>
This commit is contained in:
Alex Crichton
2020-01-17 09:43:35 -06:00
committed by GitHub
parent 7890fa6705
commit 0bee67a852
10 changed files with 384 additions and 99 deletions

View File

@@ -2,6 +2,7 @@ use crate::externals::Func;
use crate::r#ref::AnyRef;
use crate::runtime::Store;
use crate::types::ValType;
use anyhow::{bail, Result};
use std::ptr;
use wasmtime_environ::ir;
use wasmtime_jit::RuntimeValue;
@@ -188,8 +189,8 @@ impl From<RuntimeValue> for Val {
pub(crate) fn into_checked_anyfunc(
val: Val,
store: &Store,
) -> wasmtime_runtime::VMCallerCheckedAnyfunc {
match val {
) -> Result<wasmtime_runtime::VMCallerCheckedAnyfunc> {
Ok(match val {
Val::AnyRef(AnyRef::Null) => wasmtime_runtime::VMCallerCheckedAnyfunc {
func_ptr: ptr::null(),
type_index: wasmtime_runtime::VMSharedSignatureIndex::default(),
@@ -211,8 +212,8 @@ pub(crate) fn into_checked_anyfunc(
vmctx,
}
}
_ => panic!("val is not funcref"),
}
_ => bail!("val is not funcref"),
})
}
pub(crate) fn from_checked_anyfunc(