| 1 | //! # async-recursion macro
|
| 2 | //!
|
|---|
| 3 | //! [](https://crates.io/crates/async-recursion)
|
|---|
| 4 | //! [](https://crates.io/crates/async-recursion)
|
|---|
| 5 | //! [](https://github.com/dcchut/async-recursion/actions)
|
|---|
| 6 | //! 
|
|---|
| 7 | //!
|
|---|
| 8 | //! Procedural macro for recursive async functions.
|
|---|
| 9 | //!
|
|---|
| 10 | //! * [Documentation](https://docs.rs/async-recursion/)
|
|---|
| 11 | //! * Cargo package: [async-recursion](https://crates.io/crates/async-recursion)
|
|---|
| 12 | //!
|
|---|
| 13 | //! ## Motivation
|
|---|
| 14 | //! Consider the following recursive implementation of the fibonacci numbers:
|
|---|
| 15 | //!
|
|---|
| 16 | //! ```rust,compile_fail
|
|---|
| 17 | //! async fn fib(n : u32) -> u32 {
|
|---|
| 18 | //! match n {
|
|---|
| 19 | //! 0 | 1 => 1,
|
|---|
| 20 | //! _ => fib(n-1).await + fib(n-2).await
|
|---|
| 21 | //! }
|
|---|
| 22 | //! }
|
|---|
| 23 | //! ```
|
|---|
| 24 | //!
|
|---|
| 25 | //! The compiler helpfully tells us that:
|
|---|
| 26 | //!
|
|---|
| 27 | //! ```console
|
|---|
| 28 | //! error[E0733]: recursion in an `async fn` requires boxing
|
|---|
| 29 | //! --> src/main.rs:1:26
|
|---|
| 30 | //! |
|
|---|
| 31 | //! 1 | async fn fib(n : u32) -> u32 {
|
|---|
| 32 | //! | ^^^ recursive `async fn`
|
|---|
| 33 | //! |
|
|---|
| 34 | //! = note: a recursive `async fn` must be rewritten to return a boxed `dyn Future`.
|
|---|
| 35 | //! = note: consider using the `async_recursion` crate: https://crates.io/crates/async_recursion
|
|---|
| 36 | //! ```
|
|---|
| 37 | //!
|
|---|
| 38 | //! This crate provides an attribute macro to automatically convert an async function
|
|---|
| 39 | //! to one returning a boxed [`Future`](core::future::Future).
|
|---|
| 40 | //!
|
|---|
| 41 | //! ## Example
|
|---|
| 42 | //!
|
|---|
| 43 | //! ```rust
|
|---|
| 44 | //! use async_recursion::async_recursion;
|
|---|
| 45 | //!
|
|---|
| 46 | //! #[async_recursion]
|
|---|
| 47 | //! async fn fib(n : u32) -> u32 {
|
|---|
| 48 | //! match n {
|
|---|
| 49 | //! 0 | 1 => 1,
|
|---|
| 50 | //! _ => fib(n-1).await + fib(n-2).await
|
|---|
| 51 | //! }
|
|---|
| 52 | //! }
|
|---|
| 53 | //! ```
|
|---|
| 54 | //!
|
|---|
| 55 | //! ## ?Send option
|
|---|
| 56 | //!
|
|---|
| 57 | //! The returned [`Future`] has a [`Send`] bound to make sure it can be sent between threads.
|
|---|
| 58 | //! If this is undesirable you can mark that the bound should be left out like so:
|
|---|
| 59 | //!
|
|---|
| 60 | //! ```rust
|
|---|
| 61 | //! # use async_recursion::async_recursion;
|
|---|
| 62 | //!
|
|---|
| 63 | //! #[async_recursion(?Send)]
|
|---|
| 64 | //! async fn returned_future_is_not_send() {
|
|---|
| 65 | //! // ...
|
|---|
| 66 | //! }
|
|---|
| 67 | //! ```
|
|---|
| 68 | //!
|
|---|
| 69 | //! ## Sync option
|
|---|
| 70 | //!
|
|---|
| 71 | //! The returned [`Future`] doesn't have a [`Sync`] bound as it is usually not required.
|
|---|
| 72 | //! You can include a [`Sync`] bound as follows:
|
|---|
| 73 | //!
|
|---|
| 74 | //! ```rust
|
|---|
| 75 | //! # use async_recursion::async_recursion;
|
|---|
| 76 | //!
|
|---|
| 77 | //! #[async_recursion(Sync)]
|
|---|
| 78 | //! async fn returned_future_is_send_and_sync() {
|
|---|
| 79 | //! // ...
|
|---|
| 80 | //! }
|
|---|
| 81 | //! ```
|
|---|
| 82 | //!
|
|---|
| 83 | //! In detail:
|
|---|
| 84 | //!
|
|---|
| 85 | //!
|
|---|
| 86 | //! - `#[async_recursion]` modifies your function to return a boxed [`Future`] with a [`Send`] bound.
|
|---|
| 87 | //! - `#[async_recursion(?Send)]` modifies your function to return a boxed [`Future`] _without_ a [`Send`] bound.
|
|---|
| 88 | //! - `#[async_recursion(Sync)]` modifies your function to return a boxed [`Future`] with [`Send`] and [`Sync`] bounds.
|
|---|
| 89 | //!
|
|---|
| 90 | //! ### License
|
|---|
| 91 | //!
|
|---|
| 92 | //! Licensed under either of
|
|---|
| 93 | //! * Apache License, Version 2.0 (<http://www.apache.org/licenses/LICENSE-2.0>)
|
|---|
| 94 | //! * MIT license (<http://opensource.org/licenses/MIT>)
|
|---|
| 95 | //!
|
|---|
| 96 | //! at your option.
|
|---|
| 97 |
|
|---|
| 98 | extern crate proc_macro;
|
|---|
| 99 |
|
|---|
| 100 | mod expand;
|
|---|
| 101 | mod parse;
|
|---|
| 102 |
|
|---|
| 103 | use proc_macro::TokenStream;
|
|---|
| 104 | use quote::quote;
|
|---|
| 105 | use syn::parse_macro_input;
|
|---|
| 106 |
|
|---|
| 107 | #[proc_macro_attribute ]
|
|---|
| 108 | pub fn async_recursion (args: TokenStream, input: TokenStream) -> TokenStream {
|
|---|
| 109 | let mut item: AsyncItem = parse_macro_input!(input as parse::AsyncItem);
|
|---|
| 110 | let args: RecursionArgs = parse_macro_input!(args as parse::RecursionArgs);
|
|---|
| 111 |
|
|---|
| 112 | expand::expand(&mut item, &args);
|
|---|
| 113 |
|
|---|
| 114 | TokenStream::from(quote!(#item))
|
|---|
| 115 | }
|
|---|
| 116 | |
|---|
