Maybe-Async Procedure Macro
Why bother writing similar code twice for blocking and async code?
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.
Write async code with normal async
, await
, and let maybe_async
handles
those async
and await
when you need a synchronized code. Switch between
sync and async by toggling is_sync
feature gate. A handy macro to
unify unit test code is also provided.
Key features
maybe-async
offers three attribute macros: maybe_async
, must_be_sync
and must_be_async
.
These macros can be applied to trait item, trait impl, function and struct impl.
-
must_be_async
keep async. Add
async_trait
attribute macro for trait declaration or implementation to bring async fn support in traits. -
must_be_sync
Convert to sync code. Convert the async code into sync code by removing all
async move
,async
andawait
keyword -
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 meansmaybe_async
is the same asmust_be_async
:[] = "0.1"
Wanna convert async code to sync? Add
maybe_async
to dependencies with anis_sync
feature gate. In this way,maybe_async
is the same asmust_be_sync
:[] = { = "0.1", = ["is_sync"] }
-
sync_impl
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 verison, 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 shoule disappear when we want async version. -
async_impl
an async implementation shoule simply disappear when we want sync version.
-
test
handy macro to unify async and sync unit test code
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, an async and sync implementation must be written repectively.
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 and etc.
Here is a proof of concept that maybe_async
can actually free us from
writing almost the same code for sync and async.
type Response = String;
type Url = &'static str;
type Method = String;
/// InnerClient are used to actually send request,
/// which differ a lot between sync and async.
/// The higher level API for end user.
;
/// Code of upstream API are almost the same for sync and async,
/// except for async/await keyword.
/// Synchronous implementation, will be deleted when we want an async implementation.
/// Else the compiler will complain that *request is defined multiple times* and blabla.
/// Asynchronous implementation, will be deleted when we want a sync implementation
With the code above, we can toggle between a sync AWZ3 client and async one
by is_sync
feature gate when we add maybe-async
to dependency.
Example for maybe_async conversion
;
async
When maybe-async
feature gate is_sync
is NOT set, the generated code
is async code:
;
async
When maybe-async
feature gate is_sync
is set, all async keyword is
ignored and yields a sync version code:
;
License
MIT