async_recursion2/
lib.rs

1//! # async-recursion macro
2//!
3//! [![Latest version](https://img.shields.io/crates/v/async-recursion)](https://crates.io/crates/async-recursion)
4//! [![crates.io downloads](https://img.shields.io/crates/d/async_recursion)](https://crates.io/crates/async-recursion)
5//! [![Build Status](https://img.shields.io/github/actions/workflow/status/dcchut/async-recursion/ci.yml?branch=master)](https://github.com/dcchut/async-recursion/actions)
6//! ![Apache/MIT2.0 License](https://img.shields.io/crates/l/async-recursion)
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 example() {
65//!     // ...
66//! }
67//! ```
68//!
69//! In detail:
70//!
71//! - `#[async_recursion]` modifies your function to return a [`BoxFuture`], and
72//! - `#[async_recursion(?Send)]` modifies your function to return a [`LocalBoxFuture`].
73//!
74//! [`BoxFuture`]: https://docs.rs/futures/0.3.19/futures/future/type.BoxFuture.html
75//! [`LocalBoxFuture`]: https://docs.rs/futures/0.3.19/futures/future/type.LocalBoxFuture.html
76//!
77//! ### License
78//!
79//! Licensed under either of
80//!  * Apache License, Version 2.0 (<http://www.apache.org/licenses/LICENSE-2.0>)
81//!  * MIT license (<http://opensource.org/licenses/MIT>)
82//!
83//! at your option.
84
85extern crate proc_macro;
86
87mod expand;
88mod parse;
89
90use proc_macro::TokenStream;
91use quote::quote;
92use syn::parse_macro_input;
93
94#[proc_macro_attribute]
95pub fn async_recursion(args: TokenStream, input: TokenStream) -> TokenStream {
96    let mut item = parse_macro_input!(input as parse::AsyncItem);
97    let args = parse_macro_input!(args as parse::RecursionArgs);
98
99    expand::expand(&mut item, &args);
100
101    TokenStream::from(quote!(#item))
102}