Proc-macro interface for async-await export

Added support for exporting `async fn`s and `fn`s that return futures
through the proc-macro interface.

- Added `#[method(async)]`, for methods that return futures but aren't
  async themselves. This is especially useful for working around
  lifetime elision (Rust putting the lifetime of `&self` into the return
  values of `async fn`s).
- Added the `#[ctx]` attribute that denotes the async context. Special
  arguments (`#[base]`, `#[ctx]`, and possibly `#[self]` in the future)
  can now be declared in any order, so long as they precede all regular
  arguments.
- Methods without receivers can now be exported. However, they still
  currently use `Map` semantics.

Async exports are unsupported by the legacy `godot_wrap_method` shim.

Author: chitoyuu

gdnative-async/src/lib.rs

@@ -16,5 +16,5 @@ mod rt;
 
 pub use executor::{set_boxed_executor, set_executor};
 pub use future::Yield;
-pub use method::{Async, AsyncMethod, Spawner};
+pub use method::{Async, AsyncMethod, Spawner, StaticArgs, StaticArgsAsyncMethod};
 pub use rt::{register_runtime, terminate_runtime, Context};

gdnative-async/src/method.rs

@@ -5,7 +5,7 @@ use std::sync::Arc;
 use futures_task::{LocalFutureObj, LocalSpawn, SpawnError};
 
 use gdnative_core::core_types::{ToVariant, Variant};
-use gdnative_core::export::{Method, NativeClass, Varargs};
+use gdnative_core::export::{FromVarargs, Method, NativeClass, Varargs};
 use gdnative_core::log::{self, Site};
 use gdnative_core::object::TInstance;
 
@@ -36,24 +36,130 @@ pub trait AsyncMethod<C: NativeClass>: Send + Sync + 'static {
     }
 }
 
+/// Trait for async methods whose argument lists are known at compile time. Not to
+/// be confused with a "static method". When exported, such methods return
+/// `FunctionState`-like objects that can be manually resumed or yielded to completion.
+///
+/// Async methods are always spawned locally on the thread where they were created,
+/// and never sent to another thread. This is so that we can ensure the safety of
+/// emitting signals from the `FunctionState`-like object. If you need to off-load
+/// some task to another thread, consider using something like
+/// `futures::future::Remote` to spawn it remotely on a thread pool.
+pub trait StaticArgsAsyncMethod<C: NativeClass>: Send + Sync + 'static {
+    type Args: FromVarargs;
+
+    /// Spawns the future for result of this method with `spawner`. This is done so
+    /// that implementors of this trait do not have to name their future types.
+    ///
+    /// If the `spawner` object is not used, the Godot side of the call will fail, output an
+    /// error, and return a `Nil` variant.
+    fn spawn_with(&self, spawner: Spawner<'_, C, Self::Args>);
+
+    /// Returns an optional site where this method is defined. Used for logging errors in FFI wrappers.
+    ///
+    /// Default implementation returns `None`.
+    #[inline]
+    fn site() -> Option<Site<'static>> {
+        None
+    }
+}
+
+/// Adapter for methods whose arguments are statically determined. If the arguments would fail to
+/// type check, the method will print the errors to Godot's debug console and return `null`.
+#[derive(Clone, Copy, Default, Debug)]
+pub struct StaticArgs<F> {
+    f: F,
+}
+
+impl<F> StaticArgs<F> {
+    /// Wrap `f` in an adapter that implements `AsyncMethod`.
+    #[inline]
+    pub fn new(f: F) -> Self {
+        StaticArgs { f }
+    }
+}
+
+impl<C: NativeClass, F: StaticArgsAsyncMethod<C>> AsyncMethod<C> for StaticArgs<F> {
+    #[inline]
+    fn spawn_with(&self, spawner: Spawner<'_, C>) {
+        let spawner = spawner.try_map_args(|mut args| match args.read_many::<F::Args>() {
+            Ok(parsed) => {
+                if let Err(err) = args.done() {
+                    err.with_site(F::site().unwrap_or_default()).log_error();
+                    return None;
+                }
+                Some(parsed)
+            }
+            Err(errors) => {
+                for err in errors {
+                    err.with_site(F::site().unwrap_or_default()).log_error();
+                }
+                None
+            }
+        });
+
+        match spawner {
+            Ok(spawner) => F::spawn_with(&self.f, spawner),
+            Err(spawner) => spawner.spawn(|_context, _this, ()| async { Variant::nil() }),
+        }
+    }
+
+    #[inline]
+    fn site() -> Option<Site<'static>> {
+        F::site()
+    }
+}
+
 /// A helper structure for working around naming future types. See [`Spawner::spawn`].
-pub struct Spawner<'a, C: NativeClass> {
+pub struct Spawner<'a, C: NativeClass, A = Varargs<'a>> {
     sp: &'static dyn LocalSpawn,
     ctx: Context,
     this: TInstance<'a, C>,
-    args: Varargs<'a>,
+    args: A,
     result: &'a mut Option<Result<(), SpawnError>>,
     /// Remove Send and Sync
     _marker: PhantomData<*const ()>,
 }
 
-impl<'a, C: NativeClass> Spawner<'a, C> {
+impl<'a, C: NativeClass, A> Spawner<'a, C, A> {
+    fn try_map_args<F, R>(self, f: F) -> Result<Spawner<'a, C, R>, Spawner<'a, C, ()>>
+    where
+        F: FnOnce(A) -> Option<R>,
+    {
+        let Spawner {
+            sp,
+            ctx,
+            this,
+            args,
+            result,
+            ..
+        } = self;
+        match f(args) {
+            Some(args) => Ok(Spawner {
+                sp,
+                ctx,
+                this,
+                args,
+                result,
+                _marker: PhantomData,
+            }),
+            None => Err(Spawner {
+                sp,
+                ctx,
+                this,
+                args: (),
+                result,
+                _marker: PhantomData,
+            }),
+        }
+    }
+
     /// Consumes this `Spawner` and spawns a future returned by the closure. This indirection
     /// is necessary so that implementors of the `AsyncMethod` trait do not have to name their
     /// future types.
     pub fn spawn<F, R>(self, f: F)
     where
-        F: FnOnce(Arc<Context>, TInstance<'_, C>, Varargs<'_>) -> R,
+        F: FnOnce(Arc<Context>, TInstance<'_, C>, A) -> R,
         R: Future<Output = Variant> + 'static,
     {
         let ctx = Arc::new(self.ctx);
@@ -123,4 +229,8 @@ impl<C: NativeClass, F: AsyncMethod<C>> Method<C> for Async<F> {
             Variant::nil()
         }
     }
+
+    fn site() -> Option<Site<'static>> {
+        F::site()
+    }
 }

gdnative-derive/src/lib.rs

@@ -7,6 +7,7 @@ extern crate quote;
 
 use proc_macro::TokenStream;
 use proc_macro2::TokenStream as TokenStream2;
+use quote::ToTokens;
 use syn::{AttributeArgs, DeriveInput, ItemFn, ItemImpl};
 
 mod extend_bounds;
@@ -18,7 +19,12 @@ mod variant;
 
 /// Collects method signatures of all functions in a `NativeClass` that have the `#[method]` attribute and registers them with Godot.
 ///
-/// For example, in the following class
+/// **Important**: Only one `impl` block per struct may be attributed with `#[methods]`.
+///
+/// For more context, please refer to [gdnative::derive::NativeClass](NativeClass).
+///
+/// ## Example
+///
 /// ```
 /// use gdnative::prelude::*;
 ///
@@ -36,34 +42,6 @@ mod variant;
 /// }
 ///
 /// ```
-/// Will expand to
-/// ```
-/// use gdnative::prelude::*;
-/// struct Foo {}
-/// impl NativeClass for Foo {
-///     type Base = gdnative::api::Reference;
-///     type UserData = gdnative::export::user_data::LocalCellData<Self>;
-/// }
-/// impl gdnative::export::StaticallyNamed for Foo {
-///     const CLASS_NAME: &'static str = "Foo";
-/// }
-/// impl gdnative::export::NativeClassMethods for Foo {
-///     fn nativeclass_register(builder: &ClassBuilder<Self>) {
-///         use gdnative::export::*;
-///         builder.method("foo", gdnative::export::godot_wrap_method!(Foo, false, fn foo(&self, #[base] _base: &Reference, bar: i64) -> i64))
-///             .with_rpc_mode(RpcMode::Disabled)
-///             .done_stateless();
-///     }
-/// }
-/// impl Foo {
-///     fn foo(&self, _owner: &Reference, bar: i64) -> i64 {
-///         bar
-///     }
-/// }
-/// ```
-/// **Important**: Only one `impl` block per struct may be attributed with `#[methods]`.
-///
-/// For more context, please refer to [gdnative::derive::NativeClass](NativeClass).
 #[proc_macro_attribute]
 pub fn methods(meta: TokenStream, input: TokenStream) -> TokenStream {
     if syn::parse::<syn::parse::Nothing>(meta.clone()).is_err() {
@@ -237,18 +215,19 @@ pub fn profiled(meta: TokenStream, input: TokenStream) -> TokenStream {
 ///
 /// **Important**: This needs to be added to one and only one `impl` block for a given `NativeClass`.
 ///
-/// For additional details about how `#[methods]` expands, please refer to [gdnative::methods](macro@methods)
-///
 /// ### `#[method]`
 /// Registers the attributed function signature to be used by Godot.
 ///
 /// This attribute was formerly called `#[export]`, but is not directly related to the concept of
 /// [exporting](https://docs.godotengine.org/en/stable/tutorials/export/exporting_basics.html) in GDScript.
 ///
 /// A valid function signature must have:
-/// - `&self` or `&mut self` as its first parameter
-/// - Optionally, `&T` or `TRef<T>` where T refers to the type declared in `#[inherit(T)]` attribute as it's second parameter;
-///   this is typically called the _base_. The parameter must be attributed with `#[base]`.
+/// - `self`, `&self` or `&mut self` as its first parameter, if applicable.
+/// - Up of one of each of the following special arguments, in any order, denoted by the attributes:
+///     - `#[base]` - A reference to the base/owner object. This may be `&T` or `TRef<T>`m where `T` refers to
+///       the type declared in `#[inherit(T)]` attribute for the `NativeClass` type.
+///     - `#[async_ctx]` - The [async context](gdnative::tasks::Context), for async methods. See the `async` argument
+///       below.
 /// - Any number of required parameters, which must have the type `Variant` or must implement the `FromVariant` trait.
 ///  `FromVariant` is implemented for most common types.
 /// - Any number of optional parameters annotated with `#[opt]`. Same rules as for required parameters apply.
@@ -257,6 +236,10 @@ pub fn profiled(meta: TokenStream, input: TokenStream) -> TokenStream {
 ///   or be a `Variant` type.
 ///
 /// ```ignore
+/// // Associated function
+/// #[method]
+/// fn foo();
+///
 /// // No access to base parameter
 /// #[method]
 /// fn foo(&self);
@@ -268,6 +251,20 @@ pub fn profiled(meta: TokenStream, input: TokenStream) -> TokenStream {
 /// // Access base parameter as TRef<T>
 /// #[method]
 /// fn foo(&self, #[base] base: TRef<Reference>);
+///
+/// // Access only the async context. Both variations are valid.
+/// #[method]
+/// async fn foo(#[async_ctx] ctx: Arc<Context>);
+/// #[method(async)]
+/// fn foo(#[async_ctx] ctx: Arc<Context>) -> impl Future<Output = ()> + 'static;
+///
+/// // Access the base parameter as TRef<T>, and the async context. Both variations are valid.
+/// // Note the absence of `async fn`s here: this is due to a current limitation in Rust's lifetime elision rules.
+/// // See the `async` attribute argument down below for more details.
+/// #[method(async)]
+/// fn foo(&self, #[base] base: TRef<Reference>, #[async_ctx] ctx: Arc<Context>) -> impl Future<Output = ()> + 'static;
+/// #[method(async)]
+/// fn foo(&self, #[async_ctx] ctx: Arc<Context>, #[base] base: TRef<Reference>) -> impl Future<Output = ()> + 'static;
 /// ```
 ///
 /// **Note**: Marking a function with `#[method]` does not have any effect unless inside an `impl` block that has the `#[methods]` attribute.
@@ -307,6 +304,29 @@ pub fn profiled(meta: TokenStream, input: TokenStream) -> TokenStream {
 ///   }
 ///   ```
 ///
+/// - `async`
+///
+///   Marks the function as async. This is used for functions that aren't `async` themselves, but return `Future`s instead.
+///   This is especially useful for working around Rust's lifetime elision rules, which put the lifetime of `&self` into the
+///   return value for `async fn`s. The `impl Future` syntax instead allows one to explicitly specify a `'static` lifetime,
+///   as required by the async runtime:
+///
+///   ```ignore
+///   // This will NOT compile: Rust assumes that any futures returned by an `async fn` may only live as long as each of its
+///   // arguments, and there is no way to tell it otherwise. As a result, it will emit some cryptic complaints about lifetime.
+///   #[method]
+///   async fn answer(&self) -> i32 {
+///      42
+///   }
+///
+///   // This, however, compiles, thanks to the explicit `'static` lifetime in the return signature.
+///   #[method(async)]
+///   fn answer(&self) -> impl Future<Output = i32> + 'static {
+///      async { 42 }
+///   }
+///
+///   ```
+///
 ///
 /// #### `Node` virtual functions
 ///
@@ -525,7 +545,31 @@ fn crate_gdnative_core() -> proc_macro2::TokenStream {
         proc_macro_crate::FoundCrate::Itself => quote!(crate),
         proc_macro_crate::FoundCrate::Name(name) => {
             let ident = proc_macro2::Ident::new(&name, proc_macro2::Span::call_site());
-            quote!( #ident )
+            ident.to_token_stream()
+        }
+    }
+}
+
+/// Returns the (possibly renamed or imported as `gdnative`) identifier of the `gdnative_async` crate,
+/// if found.
+fn crate_gdnative_async() -> proc_macro2::TokenStream {
+    if let Ok(found_crate) = proc_macro_crate::crate_name("gdnative-async") {
+        return match found_crate {
+            proc_macro_crate::FoundCrate::Itself => quote!(crate),
+            proc_macro_crate::FoundCrate::Name(name) => {
+                let ident = proc_macro2::Ident::new(&name, proc_macro2::Span::call_site());
+                ident.to_token_stream()
+            }
+        };
+    }
+
+    let found_crate = proc_macro_crate::crate_name("gdnative").expect("crate not found");
+
+    match found_crate {
+        proc_macro_crate::FoundCrate::Itself => quote!(crate::tasks),
+        proc_macro_crate::FoundCrate::Name(name) => {
+            let ident = proc_macro2::Ident::new(&name, proc_macro2::Span::call_site());
+            quote!( #ident::tasks )
         }
     }
 }