Lines Matching full:async
1 //! **Why bother writing similar code twice for blocking and async code?**
3 …ps://github.com/fMeow/maybe-async-rs/workflows/CI%20%28Linux%29/badge.svg?branch=main)](https://gi…
5 …test Version](https://img.shields.io/crates/v/maybe-async.svg)](https://crates.io/crates/maybe-asy…
6 //! [](https://docs.rs/maybe-async)
8 //! When implementing both sync and async versions of API in a crate, most API
9 //! of the two version are almost the same except for some async/await keyword.
11 //! `maybe-async` help unifying async and sync implementation by **procedural
13 //! - Write async code with normal `async`, `await`, and let `maybe_async`
15 //! those `async` and `await` when you need a blocking code.
16 //! - Switch between sync and async by toggling `is_sync` feature gate in
31 //! version (one async and another blocking) can fail compilation.
36 //! The async/await language feature alters the async world of rust.
37 //! Comparing with the map/and_then style, now the async code really resembles
40 //! In many crates, the async and sync version of crates shares the same API,
41 //! but the minor difference that all async code must be awaited prevent the
42 //! unification of async and sync code. In other words, we are forced to write
43 //! an async and a sync implementation respectively.
47 //! `maybe-async` offers 4 set of attribute macros: `maybe_async`,
50 //! To use `maybe-async`, we must know which block of codes is only used on
51 //! blocking implementation, and which on async. These two implementation should
52 //! share the same function signatures except for async/await keywords, and use
55 //! Use `maybe_async` macro on codes that share the same API on both async and
56 //! blocking code except for async/await keywords. And use feature gate
57 //! `is_sync` in `Cargo.toml` to toggle between async and blocking code.
61 //! Offers a unified feature gate to provide sync and async conversion on
62 //! demand by feature gate `is_sync`, with **async first** policy.
64 //! Want to keep async code? add `maybe_async` in dependencies with default
72 //! Want to convert async code to sync? Add `maybe_async` to dependencies with
85 //! to support async fn in traits.
89 //! Not all async traits need futures that are `dyn Future + Send`.
91 //! to avoid having "Send" and "Sync" bounds placed on the async trait
98 //! For compatibility reasons, the `async fn` in traits is supported via a verbose `AFIT` flag.…
103 //! **Keep async**.
112 //! **Convert to sync code**. Convert the async code into sync code by
113 //! removing all `async move`, `async` and `await` keyword
119 //! must simply disappear when we want async version.
122 //! point when the async and sync version should differ greatly. For
123 //! example, a MongoDB client may use the same API for async and sync
127 //! sync implementation should disappear when we want async version.
131 //! An async implementation should on compile on async implementation and
141 //! Handy macro to unify async and sync **unit and e2e test** code.
144 //! and also the conditions to compile to async test code with given test
151 //! # async fn async_fn() -> bool {
157 //! async(
161 //! async(
166 //! async fn test_async_fn() {
174 //! `maybe-async` compiles your code in different way with the `is_sync` feature
175 //! gate. It removes all `await` and `async` keywords in your code under
185 //! async fn async_fn_name() -> Result<(), ()> {
197 //! async fn async_fn_name() -> Result<(), ()> {
206 //! async fn maybe_async_fn() -> Result<(), ()> {
214 //! When `maybe-async` feature gate `is_sync` is **NOT** set, the generated code
215 //! is async code:
220 //! async fn maybe_async_fn_name() -> Result<(), ()> {
231 //! async fn maybe_async_fn_name() -> Result<(), ()> {
239 //! async fn maybe_async_fn() -> Result<(), ()> {
246 //! When `maybe-async` feature gate `is_sync` is set, all async keyword is
283 //! API of async and sync version is almost the same, such as creating or
287 //! actually free us from writing almost the same code for sync and async. We
288 //! can toggle between a sync AWZ3 client and async one by `is_sync` feature
289 //! gate when we add `maybe-async` to dependency.
378 // acronym for Async Function in Trait, in async_mode()
383 "Only accepts `Send`, `?Send` or `AFIT` (native async function in trait)", in async_mode()
407 /// convert marked async code to async code with `async-trait`
418 /// convert marked async code to sync code
440 /// mark async implementation
469 /// Handy macro to unify test code of sync and async code
471 /// Since the API of both sync and async code are the same,
472 /// with only difference that async functions must be awaited.
473 /// So it's tedious to write unit sync and async respectively.
475 /// This macro helps unify the sync and async unit test code.
478 /// as async and the lib to run async test, e.x. `async-std::test`,
487 /// async fn async_fn() -> bool {
494 /// // when to run async test
495 /// async(all(not(feature="is_sync"), feature="async_std"), async_std::test),
496 /// // you can specify multiple conditions for different async runtime
497 /// async(all(not(feature="is_sync"), feature="tokio"), tokio::test)
499 /// async fn test_async_fn() {
506 /// async fn test_sync_fn() {
517 /// # async fn async_fn() -> bool { true }
519 /// // convert to sync version when sync condition is met, keep in async version when corresponding
532 /// async fn test_async_fn() {
565 // The rest attributes indicates async condition and async test macro in parse_test_cfg()
566 // only accepts in the forms of `async(cond, test_macro)`, but `cond` and in parse_test_cfg()
577 input.error("Must be list of metas like: `async(condition, async_test_macro)`") in parse_test_cfg()
581 if name != "async" { in parse_test_cfg()
584 format!("Unknown path: `{}`, must be `async`", name), in parse_test_cfg()
590 input.error("Must be list of metas like: `async(condition, async_test_macro)`") in parse_test_cfg()
602 "Must pass two metas or string literals like `async(condition, \ in parse_test_cfg()