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

wiggle: add support for async traits; ABI func is now generic of ctx

Browse Source 
* ctx parameter no longer accepted by wiggle::from_witx macro.
* optional async_ parameter specifies which functions are async.
* re-export async_trait::async_trait, so users don't have to take a dep.
This commit is contained in:
Pat Hickey
2021-03-04 17:26:09 -08:00
parent a5d49c07a7
commit f11cd8e7b1
9 changed files with 260 additions and 97 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") {