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

Merge pull request #2701 from bytecodealliance/pch/wiggle_async

Browse Source 
wiggle: support for Rust async
This commit is contained in:
Pat Hickey
2021-03-05 10:43:55 -08:00
committed by GitHub
parent 8854dec01d 84df5fa54a
commit ccdf6ec0b1
36 changed files with 754 additions and 152 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
crates/wiggle/macro/src/lib.rs
View File

@@ -15,9 +15,11 @@ use syn::parse_macro_input;
/// Rust-idiomatic snake\_case.
///
/// * For each `@interface func` defined in a witx module, an abi-level
/// function is generated which takes ABI-level arguments, along with a
/// "context" struct (whose type is given by the `ctx` field in the
/// macro invocation) and a `GuestMemory` implementation.
/// function is generated which takes ABI-level arguments, along with
/// a ref that impls the module trait, and a `GuestMemory` implementation.
/// Users typically won't use these abi-level functions: The `wasmtime-wiggle`
/// and `lucet-wiggle` crates adapt these to work with a particular WebAssembly
/// engine.
///
/// * A public "module trait" is defined (called the module name, in
/// SnakeCase) which has a `&self` method for each function in the
@@ -27,57 +29,94 @@ use syn::parse_macro_input;
/// Arguments are provided using Rust struct value syntax.
///
/// * `witx` takes a list of string literal paths. Paths are relative to the
/// CARGO_MANIFEST_DIR of the crate where the macro is invoked.
/// * `ctx` takes a type name. This type must implement all of the module
/// traits
/// CARGO_MANIFEST_DIR of the crate where the macro is invoked. Alternatively,
/// `witx_literal` takes a string containing a complete witx document.
/// * Optional: `errors` takes a mapping of witx identifiers to types, e.g
/// `{ errno => YourErrnoType }`. This allows you to use the `UserErrorConversion`
/// trait to map these rich errors into the flat witx type, or to terminate
/// WebAssembly execution by trapping.
/// * Optional: `async` takes a set of witx modules and functions which are
/// made Rust `async` functions in the module trait.
///
/// ## Example
///
/// ```
/// use wiggle::{GuestPtr, GuestErrorType};
///
/// /// The test witx file `arrays.witx` lives in the test directory. For a
/// /// full-fledged example with runtime tests, see `tests/arrays.rs` and
/// /// the rest of the files in that directory.
/// use wiggle::GuestPtr;
/// wiggle::from_witx!({
/// witx: ["../tests/arrays.witx"],
/// ctx: YourCtxType,
/// witx_literal: "
/// (typename $errno
/// (enum (@witx tag u32)
/// $ok
/// $invalid_arg
/// $io
/// $overflow))
/// (typename $alias_to_float f32)
/// (module $example
/// (@interface func (export \"int_float_args\")
/// (param $an_int u32)
/// (param $some_floats (list f32))
/// (result $r (expected (error $errno))))
/// (@interface func (export \"double_int_return_float\")
/// (param $an_int u32)
/// (result $r (expected $alias_to_float (error $errno)))))
/// ",
/// errors: { errno => YourRichError },
/// async: { example::double_int_return_float },
/// });
///
/// /// The `ctx` type for this wiggle invocation.
/// /// Witx generates a set of traits, which the user must impl on a
/// /// type they define. We call this the ctx type. It stores any context
/// /// these functions need to execute.
/// pub struct YourCtxType {}
///
/// /// `arrays.witx` contains one module called `arrays`. So, we must
/// /// implement this one method trait for our ctx type:
/// impl arrays::Arrays for YourCtxType {
/// /// Witx provides a hook to translate "rich" (arbitrary Rust type) errors
/// /// into the flat error enums used at the WebAssembly interface. You will
/// /// need to impl the `types::UserErrorConversion` trait to provide a translation
/// /// from this rich type.
/// #[derive(Debug)]
/// pub enum YourRichError {
/// InvalidArg(String),
/// Io(std::io::Error),
/// Overflow,
/// Trap(String),
/// }
///
/// /// The above witx text contains one module called `$example`. So, we must
/// /// implement this one method trait for our ctx type.
/// #[wiggle::async_trait(?Send)]
/// /// We specified in the `async_` field that `example::double_int_return_float`
/// /// is an asynchronous method. Therefore, we use the `async_trait` proc macro
/// /// (re-exported by wiggle from the crate of the same name) to define this
/// /// trait, so that `double_int_return_float` can be an `async fn`.
/// impl example::Example for YourCtxType {
/// /// The arrays module has two methods, shown here.
/// /// Note that the `GuestPtr` type comes from `wiggle`,
/// /// whereas the witx-defined types like `Excuse` and `Errno` come
/// /// from the `pub mod types` emitted by the `wiggle::from_witx!`
/// /// invocation above.
/// fn reduce_excuses(&self, _a: &GuestPtr<[GuestPtr<types::Excuse>]>)
/// -> Result<types::Excuse, types::Errno> {
/// fn int_float_args(&self, _int: u32, _floats: &GuestPtr<[f32]>)
/// -> Result<(), YourRichError> {
/// unimplemented!()
/// }
/// fn populate_excuses(&self, _a: &GuestPtr<[GuestPtr<types::Excuse>]>)
/// -> Result<(), types::Errno> {
/// unimplemented!()
/// async fn double_int_return_float(&self, int: u32)
/// -> Result<f32, YourRichError> {
/// Ok(int.checked_mul(2).ok_or(YourRichError::Overflow)? as f32)
/// }
/// }
///
/// /// For all types used in the `Error` position of a `Result` in the module
/// /// traits, you must implement `GuestErrorType` which tells wiggle-generated
/// /// For all types used in the `error` an `expected` in the witx document,
/// /// you must implement `GuestErrorType` which tells wiggle-generated
/// /// code what value to return when the method returns Ok(...).
/// impl GuestErrorType for types::Errno {
/// impl wiggle::GuestErrorType for types::Errno {
/// fn success() -> Self {
/// unimplemented!()
/// }
/// }
///
/// /// The `types::GuestErrorConversion` trait is also generated with a method for
/// /// each type used in the `Error` position. This trait allows wiggle-generated
/// /// each type used in the `error` position. This trait allows wiggle-generated
/// /// code to convert a `wiggle::GuestError` into the right error type. The trait
/// /// must be implemented for the user's `ctx` type.
/// /// must be implemented for the user's ctx type.
///
/// impl types::GuestErrorConversion for YourCtxType {
/// fn into_errno(&self, _e: wiggle::GuestError) -> types::Errno {
@@ -85,6 +124,26 @@ use syn::parse_macro_input;
/// }
/// }
///
/// /// If you specify a `error` mapping to the macro, you must implement the
/// /// `types::UserErrorConversion` for your ctx type as well. This trait gives
/// /// you an opportunity to store or log your rich error type, while returning
/// /// a basic witx enum to the WebAssembly caller. It also gives you the ability
/// /// to terminate WebAssembly execution by trapping.
///
/// impl types::UserErrorConversion for YourCtxType {
/// fn errno_from_your_rich_error(&self, e: YourRichError)
/// -> Result<types::Errno, wiggle::Trap>
/// {
/// println!("Rich error: {:?}", e);
/// match e {
/// YourRichError::InvalidArg{..} => Ok(types::Errno::InvalidArg),
/// YourRichError::Io{..} => Ok(types::Errno::Io),
/// YourRichError::Overflow => Ok(types::Errno::Overflow),
/// YourRichError::Trap(s) => Err(wiggle::Trap::String(s)),
/// }
/// }
/// }
///
/// # fn main() { println!("this fools doc tests into compiling the above outside a function body")
/// # }
/// ```
@@ -93,10 +152,11 @@ pub fn from_witx(args: TokenStream) -> TokenStream {
let config = parse_macro_input!(args as wiggle_generate::Config);
let doc = config.load_document();
let names = wiggle_generate::Names::new(&config.ctx.name, quote!(wiggle));
let names = wiggle_generate::Names::new(quote!(wiggle));
let error_transform = wiggle_generate::ErrorTransform::new(&config.errors, &doc)
.expect("validating error transform");
let error_transform =
wiggle_generate::CodegenSettings::new(&config.errors, &config.async_, &doc)
.expect("validating codegen settings");
let code = wiggle_generate::generate(&doc, &names, &error_transform);
let metadata = if cfg!(feature = "wiggle_metadata") {