[−][src]Crate pasts

Pasts

Minimal and simpler alternative to the futures crate.

Build Status Docs crates.io

Goals/Features

  • No required std / alloc
  • No macros at all (no pin_mut!() macros inserting unsafe blocks into your code)
  • No slow compiling proc macros (fast compile times)
  • No dependencies
  • No cost (True zero-cost abstractions!)
  • No pain (API super easy to learn & use!)
  • No unsafe code left for you to write for working with Futures

Table of Contents

Getting Started

Add the following to your Cargo.toml.

[dependencies]
pasts = "0.4"

Example

This example goes in a loop and prints "One" every second, and "Two" every other second. After 5 prints, the program prints "One" once more, then terminates.

#![forbid(unsafe_code)]

use pasts::prelude::*;
use pasts::CvarExec;

use std::cell::RefCell;

async fn timer_future(duration: std::time::Duration) {
    pasts::spawn_blocking(move || std::thread::sleep(duration)).await
}

async fn one(state: &RefCell<usize>) {
    println!("Starting task one");
    while *state.borrow() < 5 {
        timer_future(std::time::Duration::new(1, 0)).await;
        let mut state = state.borrow_mut();
        println!("One {}", *state);
        *state += 1;
    }
    println!("Finish task one");
}

async fn two(state: &RefCell<usize>) {
    println!("Starting task two");
    loop {
        timer_future(std::time::Duration::new(2, 0)).await;
        let mut state = state.borrow_mut();
        println!("Two {}", *state);
        *state += 1;
    }
}

async fn example() {
    let state = RefCell::new(0);
    let mut task_one = one(&state);
    let mut task_two = two(&state);
    let mut tasks = [task_one.fut(), task_two.fut()];
    tasks.select().await;
}

fn main() {
    static EXECUTOR: CvarExec = CvarExec::new();

    EXECUTOR.block_on(example());
}

API

API documentation can be found on docs.rs.

Features

Some APIs are only available with the std feature enabled. Other APIs only require the alloc feature. APIs that require features are labeled so on docs.rs. You can use no-std with or without the alloc feature (which corresponds to the alloc crate, just as std corresponds to the std crate).

Upgrade

You can use the changelog to facilitate upgrading this crate as a dependency.

License

Licensed under either of

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.

Contributors are always welcome (thank you for being interested!), whether it be a bug report, bug fix, feature request, feature implementation or whatever. Don't be shy about getting involved. I always make time to fix bugs, so usually a patched version of the library will be out a few days after a report. Features requests will not complete as fast. If you have any questions, design critques, or want me to find you something to work on based on your skill level, you can email me at jeronlau@plopgrizzly.com. Otherwise, here's a link to the issues on GitHub. Before contributing, check out the contribution guidelines, and, as always, make sure to follow the code of conduct.

Modules

prelude

Re-exported traits

Structs

CvarExec

std feature required. A thread-safe executor that uses a Condvar to put the thread to sleep when the future is pending.

DynFuture

A wrapper around a Future trait object.

Traits

DynBoxFut

alloc feature required. Trait for converting Pin<Box<dyn Future>>s into an abstraction of pinned trait objects.

DynFut

Trait for converting Futures into an abstraction of pinned trait objects.

Executor

An executor for Futures.

Join

Trait for joining a tuple of futures into a single future.

Select

A trait to select on a slice of Futures or Option<Future>s.

Functions

spawn_blocking

std feature required. Construct a future from a blocking function to be run on a dynamically sized thread pool.