4 releases (2 breaking)
0.3.0 | Oct 28, 2020 |
---|---|
0.2.0 | Sep 28, 2020 |
0.1.1 | Sep 9, 2020 |
0.1.0 | Sep 7, 2020 |
#3 in #gwasm
Used in gfaas
17KB
339 lines
This crate allows you to distributed heavy-workload functions to the Golem Network (or any other compatible backend when support for it is added in the future).
Quick start
The usage is pretty straightforward. In your Cargo.toml
, put gfaas
as your dependency
# Cargo.toml
[dependencies]
gfaas = "0.3"
You can now annotate some heavy-workload function to be distributed on the Golem Network like so
use gfaas::remote_fn;
#[remote_fn]
fn hello(input: String) -> String {
// let's make the input all-caps
input.to_uppercase().to_string()
}
#[actix_rt::main]
async fn main() {
let input = "hey there gfaas";
let output = hello("hey there gfaas".to_string()).await.unwrap();
assert_eq!(input.to_uppercase(), output)
}
In order to compile your code you'll need to use our custom wrapper on top of cargo
called
gfaas
. You can install the tool with cargo-install
like so
cargo install gfaas-cli
Then, you can use gfaas
like you would use cargo
. So, to build and run on Golem Network,
you'd execute
gfaas run
Notes about gfaas::remote_fn
When you annotate a function with gfaas::remote_fn
attribute, it gets expanded into a
full-fledged async function which is fallible. So for instance, the following function
use gfaas::remote_fn;
#[remote_fn]
fn hello(input: String) -> String;
expands into
async fn hello(input: String) -> Result<String, gfaas::Error>;
Therefore, it is important to remember that you need to run the function in an async block
and in order to get the result of your function back, you need to unpack it from the outer
Result
type.
The asyncness and the Result
are there due to the nature of any distributed computation
run on top of some network of nodes: it may fail due to reasons not related to your app
such as network downtime, etc.
Furthermore, the input and output arguments of your function have to be serializable, and
so they are expected to derive serde::Serialize
and serde::Deserialize
traits.
Specifying Golem's configuration parameters
You can currently set the following configuration parameters directly via gfaas::remote_fn
attribute:
- (maximum) budget in NGNT (defaults to 100):
#[remote_fn(budget = 100)]
fn hello(input: String) -> String;
- timeout in seconds (defaults to 10 minutes):
#[remote_fn(timeout = 600)]
fn hello(input: String) -> String;
- subnet tag (defaults to "devnet-alpha.2"):
#[remote_fn(subnet = "devnet-alpha.2")]
fn hello(input: String) -> String;
Of course, nobody stops you from setting any number of parameters at once
#[remote_fn(budget = 10, subnet = "my_subnet")]
fn hello(input: String) -> String;
Notes about gfaas
build tool and adding dependecies for your functions
The reason that a custom wrapper around cargo
is needed, is because the function
annotated with gfaas::remote_fn
, under-the-hood is actually automatically cross-compiled
into a WASI binary.
In addition, since the functions are cross-compiled to WASI, you need to install
wasm32-wasi
target in your used Rust toolchain. Furthermore, for that same reason, not
all crates are compatible with WASI yet, but you can manually specify which crates you
want your functions to depend on by adding a [gfaas_dependencies]
section to your Cargo.toml
# Cargo.toml
[package]
author = "Jakub Konka"
[dependecies]
actix = "1"
[gfaas_dependencies]
log = "0.4"
Notes on running your app locally (for testing)
It is well known that prior to launching our app on some distributed network of nodes, it
is convenient to first test the app locally in search of bugs and errors. This is also
possible with gfaas
. In order to force your app to run locally, simply pass
run_local=true
as argument to gfaas::remote_fn
attribute
#[remote_fn(run_local = true)]
fn hello(input: String) -> String;
This will spawn all of your annotated functions in separate threads on your machine locally, so you can verify that everything works as expected prior to launching the tasks on the Golem Network.
Examples
A couple illustrative examples of how to use this crate can be found in the examples/
directory. All examples require gfaas
build tool to be built.
Dependencies
~1.5MB
~36K SLoC