futures-rate

What is this library

This library provides easy tools to help Rust applications guide critical resources or code paths from being overwhelmed.

Depending on the configuration, the library will limit the amount of guarded futures being polled concurrently.

How to use

Installation

First of all, add the dependency to your Rust project:

bash $ cargo install futures-rate

Or in your project's Cargo.toml, add the following dependency:

toml [dependencies] futures-rate = "^0.1.0"

then run $ cargo install in your terminal from project's root directory.

Limit access rate

• Create and manage a [GateKeeper] object in your main thread, which will set the access limit to a certain resource:

```rust use futures_rate::GateKeeper;

/// then in main thread fn main() { // ... other code

// At most 10 futures can pass the gate at any given time  
let gatekeeper = GateKeeper::new(10);

// ... more code

} ```

• Then register your future to the [GateKeeper] such that the resourceful future can be protected:

```rust use futures_rate::{GateKeeper, Permit};

/// in the business logic which has access to the gatekeeper object async fn work(gatekeeper: &GateKeeper) -> usize { // create the IO-heavy future let ioFut = async { // do async work here };

let permit = gatekeeper.register(async {
    // At most 10 IO work can be on-the-fly at any given time
    ioFut.await;        

    // the result of all questions is always 42
    42
});

permit.await

} ```

Naive Future Lock

If setting the

Examples

A classic use case is to place a [GateKeeper] over an a client socket pool, such that only a limited number of future visitors can be allowed to poll the resources and hence limit the amount of open connections.

```rust use futures::{executor, future}; use futures_rate::{GateKeeper, Permit}; use std::future::Future; use std::thread; use std::time::Duration;

fn main() { let gatekeeper = GateKeeper::new(1); let futvalues = async { let fut1 = buildfut(0, &gatekeeper); let fut2 = buildfut(1, &gatekeeper); let fin = future::join(fut1, fut_2); fin.await };

 let values = executor::block_on(fut_values);

 println!("Values from fut_1={:?}", values.0);
 println!("Values from fut_2={:?}", values.1);

}

fn buildfut( offset: i32, gatekeeper: &GateKeeper, ) -> Permit, impl Future

>> { gatekeeper.register(async move { let mut values = Vec::with

capacity(100); (0..100).foreach(|v| { thread::sleep(Duration::frommillis(1)); values.push(2 * v + offset); });

     values
 }).unwrap()

} ```