Crate futures_timer

A general purpose crate for working with timeouts and delays with futures.

This crate is intended to provide general purpose timeouts and interval streams for working with futures. The implementation may not be optimized for your particular use case, though, so be sure to read up on the details if you're concerned about that!

Basic usage of this crate is relatively simple:

use std::time::Duration;
use futures_timer::Delay;
use futures::prelude::*;

let dur = Duration::from_secs(3);
let fires_in_three_seconds = Delay::new(dur)
    .map(|()| println!("prints three seconds later"));
// spawn or use the future above

In addition to a one-shot future you can also create a stream of delayed notifications with the Interval type:

use std::time::Duration;
use futures_timer::Interval;
use futures::prelude::*;

let dur = Duration::from_secs(4);
let stream = Interval::new(dur)
    .map(|()| println!("prints every four seconds"));
// spawn or use the stream

And you're off to the races! Check out the API documentation for more details about the various methods on Delay and Interval.

Implementation details

The Delay and Interval types are powered by an associated Timer. By default constructors like Delay::new and Interval::new use a global instance of Timer to power their usage. This global Timer is spawned onto a helper thread which continuously runs in the background sending out timer notifications.

If needed, however, a Timer can be constructed manually and the Delay::new_handle-style methods can be used to create delays/intervals associated with a specific instance of Timer. Each Timer has a TimerHandle type which is used to associate new objects to it.

Note that there's also a TimerHandle::set_fallback method which will globally configure the fallback timer handle as well if you'd like to run your own timer.

Finally, the implementation of Timer itself is currently a binary heap. Timer insertion is O(log n) where n is the number of active timers, and so is firing a timer (which invovles removing from the heap).

Reexports

pub use ext::FutureExt;

pub use ext::StreamExt;

Modules

ext	Extension traits for the standard Stream and Future traits.

Structs

Delay	A future representing the notification that an elapsed duration has occurred.
Interval	A stream representing notifications at fixed interval
SetDefaultError	Error returned from TimerHandle::set_fallback.
Timer	A "timer heap" used to power separately owned instances of Delay and Interval.
TimerHandle	A handle to a Timer which is used to create instances of a Delay.