↪️ Calling guest (exported) functions

Search…
A Wasm module can export entities, like functions, memories, globals and tables. This example illustrates how to call exported functions.
In this example we'll see how to use exported functions.
Exported function are the entities you will probably use the most: they will be your entrypoint to calling Wasm module logic.
Exported function come in two flavors:
Dynamic functions;
Native functions.
We'll cover both flavors in this example.
First we are going to want to initialize a new project. To do this we can navigate to our project folder, or create one. In this example, we will create a new project. Lets create it and navigate to it:
Rust
Go
Python
PHP
C/C++
Ruby
The final Rust code for this example can be found on Github: exports_function.rs.
Please take a look at the setup steps for Rust.
1
cargo new exports-function
2
cd exports-function
Copied!
We have to modify Cargo.toml to add the Wasmer dependencies as shown below:
1
[dependencies]
2
# The Wasmer API
3
wasmer = "2.0"
Copied!
The final Go code for this example can be found on Github: exports_function.go.
Please take a look at the setup steps for Go.
1
mkdir wasmer-example-exports-function
2
cd wasmer-example-exports-function
3
go mod init github.com/$USER/wasmer-example-exports-function
Copied!
The final Python code for this example can be found on Github: exports_function.py.
Please take a look at the setup steps for Python.
1
mkdir wasmer-example-exports-function
2
cd wasmer-example-exports-function
3
pip install wasmer wasmer_compiler_cranelift
Copied!
The final PHP code for this example can be found on Github: exports-function.php.
Please take a look at the setup steps for PHP.
1
mkdir wasmer-example-exports-function
2
cd wasmer-example-exports-function
3
composer init --name=wasmer-example-exports-function
4
composer require wasm/wasm
Copied!
The final C code for this example can be found on Github: instance.c.
Please take a look at the setup steps for C/C++.
1
mkdir wasmer-example-exports-function
2
cd wasmer-example-exports-function
3
vim Makefile
Copied!
Let's create a simple Makefile:
1
CFLAGS = -g -I$(shell $(WASMER_DIR)/bin/wasmer config --includedir)
2
LDFLAGS = -Wl,-rpath,$(shell $(WASMER_DIR)/bin/wasmer config --libdir)
3
LDLIBS = $(shell $(WASMER_DIR)/bin/wasmer config --libs)
4
​
5
.SILENT: exports-function exports-function.o
6
exports-function: exports-function.o
7
​
8
.PHONY: clean
9
.SILENT: clean
10
clean:
11
    rm -f exports-function.o exports-function
Copied!
The final Ruby code for this example can be found on Github: exports_function.rb.
Please take a look at the setup steps for Ruby.
1
gem install wasmer
Copied!
Now that we have everything set up, let's go ahead and try it out!
Using the dynamic flavor
We'll start by fetching the guest function and see how to call it using the dynamic flavor. Our Wasm module exports a sum function, let's get and call it:
Rust
Go
Python
PHP
C/C++
Ruby
1
let sum = instance.exports.get_function("sum")?;
2
let args = [Value::I32(1), Value::I32(2)];
3
let result: Box<[Val]> = sum.call(&args)?;
Copied!
1
sum, err := instance.Exports.GetRawFunction("sum")
2
​
3
if err != nil {
4
  panic(fmt.Sprintf("Failed to get the `%s` function: %s\n", name, err))
5
}
6
​
7
result, err := sum.Call(1, 2)
Copied!
(not possible)
1
$firstArg = Wasm\Module\Val::newI32(1);
2
$secondArg = Wasm\Module\Val::newI32(2);
3
$args = new Wasm\Vec\Val([$firstArg->inner(), $secondArg->inner()]);
4
​
5
$result = $sum($args);
Copied!
1
wasm_val_t args_val[2] = { WASM_I32_VAL(3), WASM_I32_VAL(4) };
2
wasm_val_t results_val[1] = { WASM_INIT_VAL };
3
wasm_val_vec_t args = WASM_ARRAY_VEC(args_val);
4
wasm_val_vec_t results = WASM_ARRAY_VEC(results_val);
5
​
6
if (wasm_func_call(sum_func, &args, &results)) {
7
    printf("> Error calling the `sum` function!\n");
8
​
9
    return 1;
10
}
Copied!
1
sum = instance.exports.sum
2
results = sum.call(1, 2)
Copied!
Easy right?
Both example look nice but it does not seem like we are using standard functions. In fact, we are calling an external entity. With the native flavor we can get something that feels more like we are using functions as if they were provided by the host directly.
Let's have a look at this.
Using the native flavor
Let's continue with our previous sum function and see how we can make interacting with it better. To do so, we'll be using the native flavor. With this flavor, passing arguments and getting result will feel more natural.
To use this flavor, we have the choice of fetching the function again or transforming the one we already have into a native function:
Rust
Go
Python
PHP
C/C++
Ruby
1
let sum = sum.native::<(i32, i32), i32>()?;
2
let result: i32 = sum.call(3, 4)?;
Copied!
Here we reused the previously fetched function and turned it into a native one. We could have directly fetched it as a native function:
1
let sum = instance
2
    .exports
3
    .get_native_function::<(i32, i32), i32>("sum")?;
Copied!
1
sumNative := sum.Native()
2
result, err = sumNative(3, 4)
Copied!
Here we reused the previously fetched function and turned it into a native one. We could have directly fetched it as a native function:
1
sum, err := instance.Exports.GetFunction("sum")
2
​
3
if err != nil {
4
  panic(fmt.Sprintf(
5
    "Failed to get the `%s` function: %s\n", 
6
    name, 
7
    err
8
  ))
9
}
Copied!
1
sum = instance.exports.sum
2
result = sum(3, 4)
Copied!
(not possible)
(not possible)
(not possible)
Running
We now have everything we need to run the Wasm module, let's do it!
Rust
Go
Python
PHP
C/C++
Ruby
You should be able to run it using the cargo run command. The output should look like this:
1
Compiling module...
2
Instantiating module...
3
Calling `sum` function...
4
Results: [I32(3)]
5
Calling `sum` function (natively)...
6
Results: 7
Copied!
If you want to run the examples from the Wasmer repository codebase directly, you can also do:
1
git clone https://github.com/wasmerio/wasmer.git
2
cd wasmer
3
cargo run --example exported-function --release --features "cranelift"
Copied!
You should be able to run it using the go run main.go command. The output should look like this:
1
Compiling module...
2
Instantiating module...
3
Calling `sum` function...
4
Result of the `sum` function: 3
5
Calling `sum` function (natively)...
6
Result of the `sum` function: 7
Copied!
If you want to run the examples from the Wasmer repository codebase directly, you can also do:
1
git clone https://github.com/wasmerio/wasmer-go.git
2
cd wasmer-go
3
go test examples/example_exports_function_test.go
Copied!
You should be able to run it using the python exports_function.py command.
If you want to run the examples from the Wasmer repository codebase directly, you can also do:
1
git clone https://github.com/wasmerio/wasmer-python.git
2
cd wasmer-python
3
python examples/exports_function.py
Copied!
You should be able to run it using the php exports-function.php command.
If you want to run the examples from the Wasmer PHP repository codebase directly, you can also do:
1
git clone https://github.com/wasmerio/wasmer-php.git
2
cd wasmer-php
3
make EXAMPLE=exports-function test-doc-examples
Copied!
You should be able to run it using the make clean exports-function && ./exports-function command. The output should look like this:
1
Creating the store...
2
Compiling module...
3
Creating imports...
4
Instantiating module...
5
Retrieving exports...
6
Retrieving the `sum` function...
7
Calling `sum` function...
8
Results of `sum`: 7
Copied!
If you want to run the examples from the Wasmer repository codebase directly, you can also do:
1
git clone https://github.com/wasmerio/wasmer.git
2
cd wasmer/lib/c-api/examples/exports-function.c
3
make clean exports-function
4
./exports-function
Copied!
You should be able to run it using the ruby exports_function.rb command.
If you want to run the examples from the Wasmer Ruby repository codebase directly, you can also do:
1
git clone https://github.com/wasmerio/wasmer-ruby.git
2
cd wasmer-ruby
3
ruby examples/exports_function.rb
Copied!
Imports & exports
↩️ Exposing host (imported) functions
Last modified 6mo ago
Copy link
Contents
Using the dynamic flavor
Using the native flavor
Running