[−][src]Crate wapc
wapc
The wapc
crate provides a WebAssembly host runtime that conforms to an RPC mechanism
called waPC. waPC is designed specifically to prevent either side of the call from having
to know anything about how or when memory is allocated or freed. The interface may at first appear more
"chatty" than other protocols, but the cleanliness, ease of use, and simplified developer experience
is worth the few extra nanoseconds of latency.
To use wapc
, first you'll need a waPC-compliant WebAssembly module (referred to as the guest) to load
and interpret. You can find a number of these samples available in the GitHub repository,
and anything compiled with the wascc actor SDK can also be invoked
via waPC as it is 100% waPC compliant.
To make function calls, first set your host_callback
function, a function invoked by the guest.
Then execute call
on the WapcHost
instance.
Example
extern crate wapc; use wapc::prelude::*; pub fn main() -> Result<(), Box<dyn std::error::Error>> { let module_bytes = load_file(); let mut host = WapcHost::new(|id: u64, bd: &str, ns: &str, op: &str, payload: &[u8]| { println!("Guest {} invoked '{}->{}:{}' with payload of {} bytes", id, bd, ns, op, payload.len()); Ok(vec![]) }, &module_bytes, None)?; let res = host.call("wapc:sample!Hello", b"this is a test")?; assert_eq!(res, b"hello world!"); Ok(()) }
Notes
waPC is reactive. Guest modules cannot initiate host calls without first handling a call initiated by the host. waPC will not automatically invoke any start functions--that decision is up to the waPC library consumer. Guest modules can synchronously make as many host calls as they like, but keep in mind that if a host call takes too long or fails, it'll cause the original guest call to also fail.
In summary, keep host_callback
functions fast and resilient, and do not spawn new threads
within host_callback
unless you must (and can synchronize memory access) because waPC
assumes a single-threaded execution environment. The host_callback
function intentionally
has no references to the WebAssembly module bytes or the running instance.
Modules
errors | Library-specific error types and utility functions |
prelude | Standard types typically used by consumers |
Structs
WapcHost | A WebAssembly host runtime for waPC-compliant WebAssembly modules |
WasiParams | Stores the parameters required to create a WASI instance |
Type Definitions
Result | A result type for errors that occur within the wapc library |