maybe-fut

maybe-fut

Introduction

Maybe-fut is a Rust library that provides a way to export both a sync and an async API from the same codebase. It allows you to write your code once and have it work in both synchronous and asynchronous contexts.

This is achieved through a complex mechanism of proc macros and wrappers around tokio and std libraries.

Maybe-fut provides its own type library, for fs, io, net, sync and time modules, which are designed to use std or tokio types as needed. Mind that for compatibility reasons, the io module has been re-implemented from scratch.

At runtime it checks whether the thread is running in a sync or async context and calls the appropriate function. This allows you to write your code once and have it work in both synchronous and asynchronous contexts.

This is a simple example of how it works:

Setup your logic to be exported using maybe-fut types:

use std::path::{Path, PathBuf};

use maybe_fut::fs::File;

struct FsClient {
    path: PathBuf,
}

#[maybe_fut::maybe_fut(
    sync = SyncFsClient,
    tokio = TokioFsClient,
    tokio_feature = "tokio"
)]
impl FsClient {
    /// Creates a new `FsClient` instance.
    pub fn new(path: impl AsRef<Path>) -> Self {
        Self {
            path: path.as_ref().to_path_buf(),
        }
    }

    /// Creates a new file at the specified path.
    pub async fn create(&self) -> std::io::Result<()> {
        // Create a new file at the specified path.
        let file = File::create(&self.path).await?;
        file.sync_all().await?;

        Ok(())
    }
}

If you see there is an attribute macro there, called maybe_fut. This macro takes 3 arguments:

sync: The name of the sync struct that will be generated.
tokio: The name of the async struct that will be generated.
tokio_feature: The name of the feature that will be used to enable the async struct.

Users can now access the public API exported from the library:

fn sync_main(path: &Path) -> Result<(), Box<dyn std::error::Error>> {
    println!("Running in sync mode");

    let client = SyncFsClient::new(path);
    client.create()?;

    Ok(())
}

#[cfg(feature = "tokio")]
async fn tokio_main(path: &Path) -> Result<(), Box<dyn std::error::Error>> {
    println!("Running in async mode");

    let client = TokioFsClient::new(path);
    client.create().await?;

    Ok(())
}

A full example can be found in the examples folder and can be run using the following command:

cargo run --example fs-client --features tokio-fs -- /tmp/test.txt

And the maybe_fut macro can be applied to traits as well, even combining generics:

use std::fmt::Display;

#[derive(Debug, Clone, Copy)]
struct TestStruct<T: Sized + Copy + Display> {
    value: T,
}

#[maybe_fut::maybe_fut(
    sync = SyncTestStruct,
    tokio = TokioTestStruct,
    tokio_feature = "tokio",
)]
impl<T> TestStruct<T>
where
    T: Sized + Copy + Display,
{
    /// Creates a new [`TestStruct`] instance.
    pub fn new(value: T) -> Self {
        Self { value }
    }

    /// Get underlying value.
    pub fn value(&self) -> T {
        self.value
    }
}

/// A trait to greet the user.
pub trait Greet {
    /// Greets the user with a message.
    fn greet(&self) -> String;

    // Greets the user with a message asynchronously.
    fn greet_async(&self) -> impl Future<Output = String>;
}

#[maybe_fut::maybe_fut(
    sync = SyncTestStruct,
    tokio = TokioTestStruct,
    tokio_feature = "tokio",
)]
impl<T> Greet for TestStruct<T>
where
    T: Sized + Copy + Display,
{
    fn greet(&self) -> String {
        format!("Hello, I'm {}", self.value)
    }

    async fn greet_async(&self) -> String {
        format!("Hello, I'm {}", self.value)
    }
}

#[cfg(feature = "tokio")]
{
    let test_struct = TokioTestStruct::new(42);
    test_struct.greet();
    test_struct.greet_async().await;
}

Performance

As of now, the performance of maybe-fut is on par with the tokio and std libraries. The proc macro generates code that is optimized for both synchronous and asynchronous contexts, so there is no significant overhead when using it.

This overhead is negligible, and it has been benchmarked, as shown at maybe-fut/benches/async_context.rs, and the results are actually quite good.

is_async_context        time:   [3.3511 ns 3.3567 ns 3.3621 ns]
Found 4 outliers among 100 measurements (4.00%)
  3 (3.00%) high mild
  1 (1.00%) high severe

What's the cost of a wrapper? Let's try to measure it by creating a file with tokio::fs::File::create and maybe_fut::fs::File::create:

tokio_create_file       time:   [11.529 µs 11.620 µs 11.715 µs]
Found 4 outliers among 100 measurements (4.00%)
  4 (4.00%) high mild

maybe_fut_create_file   time:   [11.603 µs 11.696 µs 11.786 µs]

So yeah, the cost of the wrapper is a very little higher, but the difference is negligible.