comm-central/third_party/rust/maybe-async/src/lib.rs

Revision control

Copy as Markdown

Other Tools

//! **Why bother writing similar code twice for blocking and async code?**
//!
//! [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
//!
//! When implementing both sync and async versions of API in a crate, most API
//! of the two version are almost the same except for some async/await keyword.
//!
//! `maybe-async` help unifying async and sync implementation by **procedural
//! macro**.
//! - Write async code with normal `async`, `await`, and let `maybe_async`
//! handles
//! those `async` and `await` when you need a blocking code.
//! - Switch between sync and async by toggling `is_sync` feature gate in
//! `Cargo.toml`.
//! - use `must_be_async` and `must_be_sync` to keep code in specified version
//! - use `async_impl` and `sync_impl` to only compile code block on specified
//! version
//! - A handy macro to unify unit test code is also provided.
//!
//! These procedural macros can be applied to the following codes:
//! - trait item declaration
//! - trait implementation
//! - function definition
//! - struct definition
//!
//! **RECOMMENDATION**: Enable **resolver ver2** in your crate, which is
//! introduced in Rust 1.51. If not, two crates in dependency with conflict
//! version (one async and another blocking) can fail compilation.
//!
//!
//! ## Motivation
//!
//! The async/await language feature alters the async world of rust.
//! Comparing with the map/and_then style, now the async code really resembles
//! sync version code.
//!
//! In many crates, the async and sync version of crates shares the same API,
//! but the minor difference that all async code must be awaited prevent the
//! unification of async and sync code. In other words, we are forced to write
//! an async and a sync implementation respectively.
//!
//! ## Macros in Detail
//!
//! `maybe-async` offers 4 set of attribute macros: `maybe_async`,
//! `sync_impl`/`async_impl`, `must_be_sync`/`must_be_async`, and `test`.
//!
//! To use `maybe-async`, we must know which block of codes is only used on
//! blocking implementation, and which on async. These two implementation should
//! share the same function signatures except for async/await keywords, and use
//! `sync_impl` and `async_impl` to mark these implementation.
//!
//! Use `maybe_async` macro on codes that share the same API on both async and
//! blocking code except for async/await keywords. And use feature gate
//! `is_sync` in `Cargo.toml` to toggle between async and blocking code.
//!
//! - `maybe_async`
//!
//! Offers a unified feature gate to provide sync and async conversion on
//! demand by feature gate `is_sync`, with **async first** policy.
//!
//! Want to keep async code? add `maybe_async` in dependencies with default
//! features, which means `maybe_async` is the same as `must_be_async`:
//!
//! ```toml
//! [dependencies]
//! maybe_async = "0.2"
//! ```
//!
//! Want to convert async code to sync? Add `maybe_async` to dependencies with
//! an `is_sync` feature gate. In this way, `maybe_async` is the same as
//! `must_be_sync`:
//!
//! ```toml
//! [dependencies]
//! maybe_async = { version = "0.2", features = ["is_sync"] }
//! ```
//!
//! There are three usage variants for `maybe_async` attribute usage:
//! - `#[maybe_async]` or `#[maybe_async(Send)]`
//!
//! In this mode, `#[async_trait::async_trait]` is added to trait declarations and trait implementations
//! to support async fn in traits.
//!
//! - `#[maybe_async(?Send)]`
//!
//! Not all async traits need futures that are `dyn Future + Send`.
//! In this mode, `#[async_trait::async_trait(?Send)]` is added to trait declarations and trait implementations,
//! to avoid having "Send" and "Sync" bounds placed on the async trait
//! methods.
//!
//! - `#[maybe_async(AFIT)]`
//!
//! AFIT is acronym for **a**sync **f**unction **i**n **t**rait, stabilized from rust 1.74
//!
//! For compatibility reasons, the `async fn` in traits is supported via a verbose `AFIT` flag. This will become
//! the default mode for the next major release.
//!
//! - `must_be_async`
//!
//! **Keep async**.
//!
//! There are three usage variants for `must_be_async` attribute usage:
//! - `#[must_be_async]` or `#[must_be_async(Send)]`
//! - `#[must_be_async(?Send)]`
//! - `#[must_be_async(AFIT)]`
//!
//! - `must_be_sync`
//!
//! **Convert to sync code**. Convert the async code into sync code by
//! removing all `async move`, `async` and `await` keyword
//!
//!
//! - `sync_impl`
//!
//! A sync implementation should compile on blocking implementation and
//! must simply disappear when we want async version.
//!
//! Although most of the API are almost the same, there definitely come to a
//! point when the async and sync version should differ greatly. For
//! example, a MongoDB client may use the same API for async and sync
//! version, but the code to actually send reqeust are quite different.
//!
//! Here, we can use `sync_impl` to mark a synchronous implementation, and a
//! sync implementation should disappear when we want async version.
//!
//! - `async_impl`
//!
//! An async implementation should on compile on async implementation and
//! must simply disappear when we want sync version.
//!
//! There are three usage variants for `async_impl` attribute usage:
//! - `#[async_impl]` or `#[async_impl(Send)]`
//! - `#[async_impl(?Send)]`
//! - `#[async_impl(AFIT)]`
//!
//! - `test`
//!
//! Handy macro to unify async and sync **unit and e2e test** code.
//!
//! You can specify the condition to compile to sync test code
//! and also the conditions to compile to async test code with given test
//! macro, e.x. `tokio::test`, `async_std::test`, etc. When only sync
//! condition is specified,the test code only compiles when sync condition
//! is met.
//!
//! ```rust
//! # #[maybe_async::maybe_async]
//! # async fn async_fn() -> bool {
//! # true
//! # }
//!
//! ##[maybe_async::test(
//! feature="is_sync",
//! async(
//! all(not(feature="is_sync"), feature="async_std"),
//! async_std::test
//! ),
//! async(
//! all(not(feature="is_sync"), feature="tokio"),
//! tokio::test
//! )
//! )]
//! async fn test_async_fn() {
//! let res = async_fn().await;
//! assert_eq!(res, true);
//! }
//! ```
//!
//! ## What's Under the Hook
//!
//! `maybe-async` compiles your code in different way with the `is_sync` feature
//! gate. It removes all `await` and `async` keywords in your code under
//! `maybe_async` macro and conditionally compiles codes under `async_impl` and
//! `sync_impl`.
//!
//! Here is a detailed example on what's going on whe the `is_sync` feature
//! gate set or not.
//!
//! ```rust
//! #[maybe_async::maybe_async(AFIT)]
//! trait A {
//! async fn async_fn_name() -> Result<(), ()> {
//! Ok(())
//! }
//! fn sync_fn_name() -> Result<(), ()> {
//! Ok(())
//! }
//! }
//!
//! struct Foo;
//!
//! #[maybe_async::maybe_async(AFIT)]
//! impl A for Foo {
//! async fn async_fn_name() -> Result<(), ()> {
//! Ok(())
//! }
//! fn sync_fn_name() -> Result<(), ()> {
//! Ok(())
//! }
//! }
//!
//! #[maybe_async::maybe_async]
//! async fn maybe_async_fn() -> Result<(), ()> {
//! let a = Foo::async_fn_name().await?;
//!
//! let b = Foo::sync_fn_name()?;
//! Ok(())
//! }
//! ```
//!
//! When `maybe-async` feature gate `is_sync` is **NOT** set, the generated code
//! is async code:
//!
//! ```rust
//! // Compiled code when `is_sync` is toggled off.
//! trait A {
//! async fn maybe_async_fn_name() -> Result<(), ()> {
//! Ok(())
//! }
//! fn sync_fn_name() -> Result<(), ()> {
//! Ok(())
//! }
//! }
//!
//! struct Foo;
//!
//! impl A for Foo {
//! async fn maybe_async_fn_name() -> Result<(), ()> {
//! Ok(())
//! }
//! fn sync_fn_name() -> Result<(), ()> {
//! Ok(())
//! }
//! }
//!
//! async fn maybe_async_fn() -> Result<(), ()> {
//! let a = Foo::maybe_async_fn_name().await?;
//! let b = Foo::sync_fn_name()?;
//! Ok(())
//! }
//! ```
//!
//! When `maybe-async` feature gate `is_sync` is set, all async keyword is
//! ignored and yields a sync version code:
//!
//! ```rust
//! // Compiled code when `is_sync` is toggled on.
//! trait A {
//! fn maybe_async_fn_name() -> Result<(), ()> {
//! Ok(())
//! }
//! fn sync_fn_name() -> Result<(), ()> {
//! Ok(())
//! }
//! }
//!
//! struct Foo;
//!
//! impl A for Foo {
//! fn maybe_async_fn_name() -> Result<(), ()> {
//! Ok(())
//! }
//! fn sync_fn_name() -> Result<(), ()> {
//! Ok(())
//! }
//! }
//!
//! fn maybe_async_fn() -> Result<(), ()> {
//! let a = Foo::maybe_async_fn_name()?;
//! let b = Foo::sync_fn_name()?;
//! Ok(())
//! }
//! ```
//!
//! ## Examples
//!
//! ### rust client for services
//!
//! When implementing rust client for any services, like awz3. The higher level
//! API of async and sync version is almost the same, such as creating or
//! deleting a bucket, retrieving an object, etc.
//!
//! The example `service_client` is a proof of concept that `maybe_async` can
//! actually free us from writing almost the same code for sync and async. We
//! can toggle between a sync AWZ3 client and async one by `is_sync` feature
//! gate when we add `maybe-async` to dependency.
//!
//!
//! # License
//! MIT
extern crate proc_macro;
use proc_macro::TokenStream;
use proc_macro2::{Span, TokenStream as TokenStream2};
use syn::{
ext::IdentExt,
parenthesized,
parse::{ParseStream, Parser},
parse_macro_input, token, Ident, ImplItem, LitStr, Meta, Result, Token, TraitItem,
};
use quote::quote;
use crate::{parse::Item, visit::AsyncAwaitRemoval};
mod parse;
mod visit;
enum AsyncTraitMode {
Send,
NotSend,
Off,
}
fn convert_async(input: &mut Item, async_trait_mode: AsyncTraitMode) -> TokenStream2 {
match input {
Item::Trait(item) => match async_trait_mode {
AsyncTraitMode::Send => quote!(#[async_trait::async_trait]#item),
AsyncTraitMode::NotSend => quote!(#[async_trait::async_trait(?Send)]#item),
AsyncTraitMode::Off => quote!(#item),
},
Item::Impl(item) => {
let async_trait_mode = item
.trait_
.as_ref()
.map_or(AsyncTraitMode::Off, |_| async_trait_mode);
match async_trait_mode {
AsyncTraitMode::Send => quote!(#[async_trait::async_trait]#item),
AsyncTraitMode::NotSend => quote!(#[async_trait::async_trait(?Send)]#item),
AsyncTraitMode::Off => quote!(#item),
}
}
Item::Fn(item) => quote!(#item),
Item::Static(item) => quote!(#item),
}
}
fn convert_sync(input: &mut Item) -> TokenStream2 {
match input {
Item::Impl(item) => {
for inner in &mut item.items {
if let ImplItem::Fn(ref mut method) = inner {
if method.sig.asyncness.is_some() {
method.sig.asyncness = None;
}
}
}
AsyncAwaitRemoval.remove_async_await(quote!(#item))
}
Item::Trait(item) => {
for inner in &mut item.items {
if let TraitItem::Fn(ref mut method) = inner {
if method.sig.asyncness.is_some() {
method.sig.asyncness = None;
}
}
}
AsyncAwaitRemoval.remove_async_await(quote!(#item))
}
Item::Fn(item) => {
if item.sig.asyncness.is_some() {
item.sig.asyncness = None;
}
AsyncAwaitRemoval.remove_async_await(quote!(#item))
}
Item::Static(item) => AsyncAwaitRemoval.remove_async_await(quote!(#item)),
}
}
fn async_mode(arg: &str) -> Result<AsyncTraitMode> {
match arg {
"" | "Send" => Ok(AsyncTraitMode::Send),
"?Send" => Ok(AsyncTraitMode::NotSend),
// acronym for Async Function in Trait,
// TODO make AFIT as default in future release
"AFIT" => Ok(AsyncTraitMode::Off),
_ => Err(syn::Error::new(
Span::call_site(),
"Only accepts `Send`, `?Send` or `AFIT` (native async function in trait)",
)),
}
}
/// maybe_async attribute macro
///
/// Can be applied to trait item, trait impl, functions and struct impls.
#[proc_macro_attribute]
pub fn maybe_async(args: TokenStream, input: TokenStream) -> TokenStream {
let mode = match async_mode(args.to_string().replace(" ", "").as_str()) {
Ok(m) => m,
Err(e) => return e.to_compile_error().into(),
};
let mut item = parse_macro_input!(input as Item);
let token = if cfg!(feature = "is_sync") {
convert_sync(&mut item)
} else {
convert_async(&mut item, mode)
};
token.into()
}
/// convert marked async code to async code with `async-trait`
#[proc_macro_attribute]
pub fn must_be_async(args: TokenStream, input: TokenStream) -> TokenStream {
let mode = match async_mode(args.to_string().replace(" ", "").as_str()) {
Ok(m) => m,
Err(e) => return e.to_compile_error().into(),
};
let mut item = parse_macro_input!(input as Item);
convert_async(&mut item, mode).into()
}
/// convert marked async code to sync code
#[proc_macro_attribute]
pub fn must_be_sync(_args: TokenStream, input: TokenStream) -> TokenStream {
let mut item = parse_macro_input!(input as Item);
convert_sync(&mut item).into()
}
/// mark sync implementation
///
/// only compiled when `is_sync` feature gate is set.
/// When `is_sync` is not set, marked code is removed.
#[proc_macro_attribute]
pub fn sync_impl(_args: TokenStream, input: TokenStream) -> TokenStream {
let input = TokenStream2::from(input);
let token = if cfg!(feature = "is_sync") {
quote!(#input)
} else {
quote!()
};
token.into()
}
/// mark async implementation
///
/// only compiled when `is_sync` feature gate is not set.
/// When `is_sync` is set, marked code is removed.
#[proc_macro_attribute]
pub fn async_impl(args: TokenStream, _input: TokenStream) -> TokenStream {
let mode = match async_mode(args.to_string().replace(" ", "").as_str()) {
Ok(m) => m,
Err(e) => return e.to_compile_error().into(),
};
let token = if cfg!(feature = "is_sync") {
quote!()
} else {
let mut item = parse_macro_input!(_input as Item);
convert_async(&mut item, mode)
};
token.into()
}
fn parse_nested_meta_or_str(input: ParseStream) -> Result<TokenStream2> {
if let Some(s) = input.parse::<Option<LitStr>>()? {
let tokens = s.value().parse()?;
Ok(tokens)
} else {
let meta: Meta = input.parse()?;
Ok(quote!(#meta))
}
}
/// Handy macro to unify test code of sync and async code
///
/// Since the API of both sync and async code are the same,
/// with only difference that async functions must be awaited.
/// So it's tedious to write unit sync and async respectively.
///
/// This macro helps unify the sync and async unit test code.
/// Pass the condition to treat test code as sync as the first
/// argument. And specify the condition when to treat test code
/// as async and the lib to run async test, e.x. `async-std::test`,
/// `tokio::test`, or any valid attribute macro.
///
/// **ATTENTION**: do not write await inside a assert macro
///
/// - Examples
///
/// ```rust
/// #[maybe_async::maybe_async]
/// async fn async_fn() -> bool {
/// true
/// }
///
/// #[maybe_async::test(
/// // when to treat the test code as sync version
/// feature="is_sync",
/// // when to run async test
/// async(all(not(feature="is_sync"), feature="async_std"), async_std::test),
/// // you can specify multiple conditions for different async runtime
/// async(all(not(feature="is_sync"), feature="tokio"), tokio::test)
/// )]
/// async fn test_async_fn() {
/// let res = async_fn().await;
/// assert_eq!(res, true);
/// }
///
/// // Only run test in sync version
/// #[maybe_async::test(feature = "is_sync")]
/// async fn test_sync_fn() {
/// let res = async_fn().await;
/// assert_eq!(res, true);
/// }
/// ```
///
/// The above code is transcripted to the following code:
///
/// ```rust
/// # use maybe_async::{must_be_async, must_be_sync, sync_impl};
/// # #[maybe_async::maybe_async]
/// # async fn async_fn() -> bool { true }
///
/// // convert to sync version when sync condition is met, keep in async version when corresponding
/// // condition is met
/// #[cfg_attr(feature = "is_sync", must_be_sync, test)]
/// #[cfg_attr(
/// all(not(feature = "is_sync"), feature = "async_std"),
/// must_be_async,
/// async_std::test
/// )]
/// #[cfg_attr(
/// all(not(feature = "is_sync"), feature = "tokio"),
/// must_be_async,
/// tokio::test
/// )]
/// async fn test_async_fn() {
/// let res = async_fn().await;
/// assert_eq!(res, true);
/// }
///
/// // force converted to sync function, and only compile on sync condition
/// #[cfg(feature = "is_sync")]
/// #[test]
/// fn test_sync_fn() {
/// let res = async_fn();
/// assert_eq!(res, true);
/// }
/// ```
#[proc_macro_attribute]
pub fn test(args: TokenStream, input: TokenStream) -> TokenStream {
match parse_test_cfg.parse(args) {
Ok(test_cfg) => [test_cfg.into(), input].into_iter().collect(),
Err(err) => err.to_compile_error().into(),
}
}
fn parse_test_cfg(input: ParseStream) -> Result<TokenStream2> {
if input.is_empty() {
return Err(syn::Error::new(
Span::call_site(),
"Arguments cannot be empty, at least specify the condition for sync code",
));
}
// The first attributes indicates sync condition
let sync_cond = input.call(parse_nested_meta_or_str)?;
let mut ts = quote!(#[cfg_attr(#sync_cond, maybe_async::must_be_sync, test)]);
// The rest attributes indicates async condition and async test macro
// only accepts in the forms of `async(cond, test_macro)`, but `cond` and
// `test_macro` can be either meta attributes or string literal
let mut async_conditions = Vec::new();
while !input.is_empty() {
input.parse::<Token![,]>()?;
if input.is_empty() {
break;
}
if !input.peek(Ident::peek_any) {
return Err(
input.error("Must be list of metas like: `async(condition, async_test_macro)`")
);
}
let name = input.call(Ident::parse_any)?;
if name != "async" {
return Err(syn::Error::new(
name.span(),
format!("Unknown path: `{}`, must be `async`", name),
));
}
if !input.peek(token::Paren) {
return Err(
input.error("Must be list of metas like: `async(condition, async_test_macro)`")
);
}
let nested;
parenthesized!(nested in input);
let list = nested.parse_terminated(parse_nested_meta_or_str, Token![,])?;
let len = list.len();
let mut iter = list.into_iter();
let (Some(async_cond), Some(async_test), None) = (iter.next(), iter.next(), iter.next())
else {
let msg = format!(
"Must pass two metas or string literals like `async(condition, \
async_test_macro)`, you passed {len} metas.",
);
return Err(syn::Error::new(name.span(), msg));
};
let attr = quote!(
#[cfg_attr(#async_cond, maybe_async::must_be_async, #async_test)]
);
async_conditions.push(async_cond);
ts.extend(attr);
}
Ok(if !async_conditions.is_empty() {
quote! {
#[cfg(any(#sync_cond, #(#async_conditions),*))]
#ts
}
} else {
quote! {
#[cfg(#sync_cond)]
#ts
}
})
}