smol-rs / smol-macros

Macros for using smol-rs

smol-macros

Macros for using smol-rs.

One of the advantages of smol is that it lets you set up your own executor, optimized for your own use cases. However, quick scaffolding is important for many organizational use cases. Especially when sane defaults are appreciated, setting up your own executor is a waste of time.

This crate provides macros for setting up an efficient smol runtime quickly and effectively. It provides sane defaults that are useful for most applications.

Simple Executor

Just have an async main function, using the [main] macro.

use smol_macros::main;

main! {
    async fn main() {
        println!("Hello, world!");
    }
}

This crate uses declarative macros rather than procedural macros, in order to avoid needing to use heavy macro dependencies. If you want to use the proc macro syntax, you can use the macro_rules_attribute::apply function to emulate it.

The following is equivalent to the previous example.

use macro_rules_attribute::apply;
use smol_macros::main;

#[apply(main!)]
async fn main() {
    println!("Hello, world!");
}

Task-Based Executor

This crate re-exports smol::Executor. If that is used as the first parameter in a function in [main], it will automatically create the executor.

use macro_rules_attribute::apply;
use smol_macros::{main, Executor};

#[apply(main!)]
async fn main(ex: &Executor<'_>) {
    ex.spawn(async { println!("Hello world!"); }).await;
}

If the thread-safe smol::Executor is used here, a thread pool will be spawned to run the executor on multiple threads. For the thread-unsafe smol::LocalExecutor, no threads will be spawned.

See documentation for the [main] function for more details.

Tests

Use the [test] macro to set up test cases that run self-contained executors.

use macro_rules_attribute::apply;
use smol_macros::{test, Executor};

#[apply(test!)]
async fn do_test(ex: &Executor<'_>) {
    ex.spawn(async {
        assert_eq!(1 + 1, 2);
    }).await;
}

MSRV Policy

The Minimum Supported Rust Version (MSRV) of this crate is 1.63. As a tentative policy, the MSRV will not advance past the current Rust version provided by Debian Stable. At the time of writing, this version of Rust is 1.63. However, the MSRV may be advanced further in the event of a major ecosystem shift or a security vulnerability.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

smol-macros's Issues

Support tests that return `Result<T, E>`

First off: thanks for the crate, it makes getting started writing tests pretty easy to work with.

In regular (standard, not async) Rust we can do:

#[cfg(test)]
mod tests {
    use super::*;
    use std::error::Error;

    #[test]
    fn it_works() -> Result<(), Box<dyn Error>> {
        let _ = f32::try_from(20usize)?;
        Ok(())
    }
}

However, the test! macro doesn't support this form at all, and assumes that all tests return ().

This means that we can't write:

#[cfg(test)]
mod tests {
    use super::*;
    macro_rules_attribute::apply;
    use std::error::Error;

    #[apply(smol_macros::test!]
    async fn it_works(_ex: &Executor<'_>) -> Result<(), Box<dyn Error>> {
        let _ = f32::try_from(20usize)?;
        Ok(())
    }
}

The current workaround to this is to just .unwrap or .expect all Result types in the function. Materially, they don't really change the logic of the test (since a panic means failure), but it is often nice to be able to write the code with ? and FromResidual only because the tests can often serve as an example for how code should be written in practice.

Thoughts? Would the current macro be able to be reworked so that the return type for a test can be set as well?

Add the ability to use futures_lite::future::block_on instead of async_io::block_on

For async programs that aren't I/O bound, they might prefer to use the non-reactor block_on and save dependencies/complexity.