async_closure

This crate utilizes the nightly-only feature [async_fn_in_trait] to imitate [async_closures].

You don't have to Box the return Future from a local closure in async code this time!

The steps to use this crate: 1. Choose an async trait which is used in trait bounds * use traits in [capture_no_lifetimes] mod when you're sure there won't be any temporarily referenced type to be captured (i.e. all captured types statisfy 'static bound). * otherwise, use traits in [capture_lifetimes] mod.

```rust,ignore
// e.g. take a closure that potentially captures references and will only be used once.

// 0. import the `AsyncFnOnce` trait and companion macro `async_closure`
#![feature(async_fn_in_trait)]
#![allow(incomplete_features)]
use async_closure::{capture_lifetimes::AsyncFnOnce, async_closure};

// 1. Adjust your caller where the trait bound looks like the following
async fn take_a_mut_closure<'env, T, F>(mut cb: F) -> T
where
    // 'env means the lifetime of captured variables outside the function
    // 'any means the lifetime of arguments coming from inside the function
    // also note how we express and represent one argument via `(arg1, )`,
    // likewise we can declare more arguments via `(arg1, arg2, arg3, )` etc.
    F: for<'any> AsyncFnMut<'env, (&'any str,), Output = T>,
{
    let mut s = String::from("-");
    let args = (&s[..],); // type inference doesn't work well here
    cb.call_mut(args).await;

    s.push('+');
    let args = (&s[..],);
    cb.call_mut(args).await
}
```

1. Use its companion macro to auto generate a value, the type of which is distinct and unnamed but implmented with the trait. The syntax in macros contains two parts:

   • For capture_lifetimes style macros:

     1. a block {} where multiple assignments field_name: field_type = field_value seperated by , are declared
     2. an async closure async |arg1: arg1_type, ...| -> return_type { /* any async code here */ }

     Note: AsyncFn* family only contains single lifetime parameter 'a, and you must use it in field_type and return_type to express the non-static referenced type. But if the type there doesn't contain a reference, 'a is needless.

   ```rust,ignore let (outer, mut buf, buffer) = (String::new(), String::new(), String::new());

   // 2. Define a capturing closure let cb1 = asyncclosuremut!({ s: &'a str = &outer, // shared reference buf: &'a mut String = &mut buf, // mutable reference arc: Arc = buffer.into(), // owned type without explicit mutation len: usize = 0, // owned type with mutation, see the code below }; async |arg: &str| -> Result> // Annotate both inputs and output: no lifetime parameter on arguments' type! { // Write async code here, using the field names and argument names as variables. // Note: the type of fields here depends on AsyncFn*. // i.e. for this macro, all field comes from let Self { pattern_match } = &mut self; // thus s: &mut &'a str, buf: &mut &'a mut String etc. // If you use async_closure!, then s: &&'a str, buf: &&'a mut String etc. // If you use async_closure_once!, then s: &'a str, buf: &'a mut String etc.

   tokio::spawn({
       let arc = arc.clone();
       async move { arc }
   }).await?;
   buf.push_str(arg);
   dbg!(&arc, &buf, &s, &arg);
   *len += arc.len() + buf.len() + s.len() + arg.len();
   Ok(*len)
   

   }); ```

   • For non capture_lifetimes style macros, same components except that
     • you can't use 'a
       • i.e. field_type and return_type can't be temporary referenced types

2. Pass the value into the caller function

   rust,ignore take_a_mut_closure(cb1).await.unwrap(); // That's it :)

| macro | trait | capture references | mutate fields | times to be used | |-------------------------------|---------------------------------------|:------------------:|:-------------:|:----------------:| | [async_closure!] | [capture_lifetimes::AsyncFn] | √ | × | no limit | | [async_closure_mut!] | [capture_lifetimes::AsyncFnMut] | √ | √ | no limit | | [async_closure_once!] | [capture_lifetimes::AsyncFnOnce] | √ | √ | 1 | | [async_owned_closure!] | [capture_no_lifetimes::AsyncFn] | × | × | no limit | | [async_owned_closure_mut!] | [capture_no_lifetimes::AsyncFnMut] | × | √ | no limit | | [async_owned_closure_once!] | [capture_no_lifetimes::AsyncFnOnce] | × | √ | 1 |