T0b1/wasmtime
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Expand Func documentation, rewrite Rust embed docs (#1236)

Browse Source 
This commit expands the documentation of the `Func` type as well as
updating the Rust embedding tutorial with more recent APIs. I wanted to
also leave space in the Rust tutorial to get more ambitious over time
with what it's documenting, but I stopped around here, curious to see
what others think about it!
This commit is contained in:
Alex Crichton
2020-03-05 12:54:42 -06:00
committed by GitHub
parent 6f88fd9af1
commit 85fab0ab56
2 changed files with 342 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

242
docs/embed-rust.md
View File

@@ -1,14 +1,21 @@
# Embedding Wasmtime in Rust
This document shows how to embed Wasmtime using the Rust API, and run a simple
wasm program.
This document shows an example of how to embed Wasmtime using the [Rust
API][apidoc] to execute a simple wasm program. Be sure to also check out the
[full API documentation][apidoc] for a full listing of what the [`wasmtime`
crate][crate] has to offer.
# Create some wasm
[apidoc]: https://bytecodealliance.github.io/wasmtime/api/wasmtime/
[wasmtime]: https://crates.io/crates/wasmtime
Let's create a simple WebAssembly file with a single exported function that returns an integer:
## Creating the WebAssembly to execute
Creation of a WebAssembly file is generally covered by the [Writing
WebAssembly chapter](./wasm.md), so we'll just assume that you've already got a
wasm file on hand for the rest of this tutorial. To make things simple we'll
also just assume you've got a `hello.wat` file which looks like this:
```wat
(;; wat2wasm hello.wat -o $WASM_FILES/hello.wasm ;;)
(module
(func (export "answer") (result i32)
i32.const 42
@@ -16,135 +23,148 @@ Let's create a simple WebAssembly file with a single exported function that retu
)
```
# Create rust project
Here we're just exporting one function which returns an integer that we'll read
from Rust.
## Hello, World!
First up let's create a rust project
```sh
$ cargo new --bin wasmtime_hello
$ cd wasmtime_hello
$ cp $WASM_FILES/hello.wasm .
```
We will be using the wasmtime engine/API to run the wasm file, so we will add the dependency to `Cargo.toml`:
Next you'll want to add `hello.wat` to the root of your project.
We will be using the `wasmtime` crate to run the wasm file, so next up we need a
dependency in `Cargo.toml`:
```toml
[dependencies]
wasmtime = "<current version>"
wasmtime = "0.12.0"
```
where "<current version>" is the current version number of the `wasmtime` crate.
It is time to add code to the `src/main.rs`. First, storage needs to be activated:
```rust
# extern crate wasmtime;
use wasmtime::*;
let store = Store::default();
```
The `hello.wasm` can be read from the file system and provided to the `Module` object constructor as `&[u8]`:
```rust,no_run
# extern crate wasmtime;
# use wasmtime::*;
# fn main() -> Result<(), Box<dyn std::error::Error>> {
# let store = Store::default();
use std::fs::read;
let hello_wasm = read("hello.wasm")?;
let module = Module::new(&store, &hello_wasm)?;
# Ok(())
# }
```
The module instance can now be created. Normally, you would provide imports, but
in this case, there are none required:
```rust
# extern crate wasmtime;
# use wasmtime::*;
# fn main() -> Result<(), Box<dyn std::error::Error>> {
# let store = Store::default();
# let module = Module::new(&store, "(module)")?;
let instance = Instance::new(&module, &[])?;
# Ok(())
# }
```
Everything is set. If a WebAssembly module has a start function -- it was run.
The instance's exports can be used at this point. wasmtime provides functions
to get an export by name, and ensure that it's a function:
```rust
# extern crate wasmtime;
# use wasmtime::*;
# fn main() -> Result<(), Box<dyn std::error::Error>> {
# let store = Store::default();
# let module = Module::new(&store, r#"(module (func (export "answer")))"#)?;
# let instance = Instance::new(&module, &[])?;
let answer = instance.get_export("answer").expect("answer").func().expect("function");
# Ok(())
# }
```
The exported function can be called using the `call` method. The exported
"answer" function accepts no parameters and returns a single `i32` value.
```rust
# extern crate wasmtime;
# use wasmtime::*;
# fn main() -> Result<(), Box<dyn std::error::Error>> {
# let store = Store::default();
# let module = Module::new(&store, r#"(module (func (export "answer") (result i32) i32.const 2))"#)?;
# let instance = Instance::new(&module, &[])?;
# let answer = instance.get_export("answer").expect("answer").func().expect("function");
let result = answer.call(&[])?;
println!("Answer: {:?}", result[0].i32());
# Ok(())
# }
```
Since we know the signature of the function ahead of time, we can also assert
its signature and call the function directly without doing conversions:
```rust
# extern crate wasmtime;
# use wasmtime::*;
# fn main() -> Result<(), Box<dyn std::error::Error>> {
# let store = Store::default();
# let module = Module::new(&store, r#"(module (func (export "answer") (result i32) i32.const 2))"#)?;
# let instance = Instance::new(&module, &[])?;
# let answer = instance.get_export("answer").expect("answer").func().expect("function");
let answer = answer.get0::<i32>()?;
let result: i32 = answer()?;
println!("Answer: {}", result);
# Ok(())
# }
```
The names of the WebAssembly module's imports and exports can be discovered by
means of module's corresponding methods.
# src/main.rs
Next up let's write the code that we need to execute this wasm file. The
simplest version of this looks like so:
```rust,no_run
# extern crate wasmtime;
use std::error::Error;
use std::fs::read;
use wasmtime::*;
fn main() -> Result<(), Box<dyn Error>> {
// A `Store` is a sort of "global object" in a sense, but for now it suffices
// to say that it's generally passed to most constructors.
let store = Store::default();
let wasm = read("hello.wasm")?;
# if false {
// We start off by creating a `Module` which represents a compiled form
// of our input wasm module. In this case it'll be JIT-compiled after
// we parse the text format.
let module = Module::from_file(&store, "hello.wat")?;
# }
# let module = Module::new(&store, r#"(module (func (export "answer") (result i32) i32.const 42))"#)?;
let module = Module::new(&store, &wasm)?;
// After we have a compiled `Module` we can then instantiate it, creating
// an `Instance` which we can actually poke at functions on.
let instance = Instance::new(&module, &[])?;
let answer = instance.get_export("answer").expect("answer").func().expect("function");
let result = answer.call(&[])?;
println!("Answer: {:?}", result[0].i32());
// The `Instance` gives us access to various exported functions and items,
// which we access here to pull out our `answer` exported function and
// run it.
let answer = instance.get_export("answer")
.expect("export named `answer` not found")
.func()
.expect("export `answer` was not a function");
// There's a few ways we can call the `answer` `Func` value. The easiest
// is to statically assert its signature with `get0` (in this case asserting
// it takes no arguments and returns one i32) and then call it.
let answer = answer.get0::<i32>()?;
// And finally we can call our function! Note that the error propagation
// with `?` is done to handle the case where the wasm function traps.
let result = answer()?;
println!("Answer: {:?}", result);
Ok(())
}
```
We can build and execute our example with `cargo run`. Note that by depending on
`wasmtime` you're depending on a JIT compiler, so it may take a moment to build
all of its dependencies:
```sh
$ cargo run
Compiling ...
...
Finished dev [unoptimized + debuginfo] target(s) in 42.32s
Running `wasmtime_hello/target/debug/wasmtime_hello`
Answer: 42
```
and there we go! We've now executed our first WebAssembly in `wasmtime` and
gotten the result back.
## Importing Host Functionality
What we've just seen is a pretty small example of how to call a wasm function
and take a look at the result. Most interesting wasm modules, however, are going
to import some functions to do something a bit more interesting. For that you'll
need to provide imported functions from Rust for wasm to call!
Let's take a look at a wasm module which imports a logging function as well as
some simple arithmetic from the environment.
```wat
(module
(import "" "log" (func $log (param i32)))
(import "" "double" (func $double (param i32) (result i32)))
(func (export "run") (result i32)
i32.const 0
call $log
i32.const 1
call $log
i32.const 2
call $double
call $log
)
)
```
This wasm module will call our `"log"` import a few times and then also call the
`"double"` import. We can compile and instantiate this module with code that
looks like this:
```rust,no_run
# extern crate wasmtime;
# use std::error::Error;
# use wasmtime::*;
# fn main() -> Result<(), Box<dyn Error>> {
# let store = Store::default();
# let module = Module::new(&store, r#"
# (module
# (import "" "log" (func $log (param i32)))
# (import "" "double" (func $double (param i32) (result i32))))"#)?;
// First we can create our `log` function, which will simply print out the
// parameter it receives.
let log = Func::wrap1(&store, |param: i32| {
println!("log: {}", param);
});
// Next we can create our double function which doubles the input it receives.
let double = Func::wrap1(&store, |param: i32| param * 2);
// When instantiating the module we now need to provide the imports to the
// instantiation process. This is the second slice argument, where each
// entry in the slice must line up with the imports in the module.
let instance = Instance::new(&module, &[log.into(), double.into()])?;
# Ok(())
# }
```
Note that there's a number of ways to define a `Func`, be sure to [consult its
documentation][`Func`] for other ways to create a host-defined function.
[`Func`]: https://bytecodealliance.github.io/wasmtime/api/wasmtime/struct.Func.html