matklad / futures-rs

Zero-cost futures and streams in Rust

futures-rs

This library is an implementation of zero cost futures in Rust.

Documentation

Tutorial

Usage

First, add this to your Cargo.toml:

[dependencies]
futures = { git = "https://github.com/alexcrichton/futures-rs" }

Next, add this to your crate:

extern crate futures;

use futures::Future;

And then, use futures! If this is your first time with futures in Rust, or at all, check out the tutorial.

What's using futures?

• futures - the core abstraction of zero-cost futures
• futures-cpupool - a thread pool for compute-bound work in event loops
• tokio-core - a concrete implementation of TCP/UDP abstractions backed by mio composable with types implementing Future
• tokio-proto - abstractions for easily writing new and composable protocols on top of tokio-core
• tokio-socks5 - an implementation of an efficient SOCKSv5 proxy server showcasing futures and tokio-core
• tokio-tls - TLS/SSL streams built on futures, implementing both client and server side connections, with support for the native system library on all platforms
• tokio-curl - an asynchronous HTTP client backed by libcurl exposed through futures
• tokio-uds - bindings for Unix domain sockets and futures
• tokio-minihttp - a simple HTTP server with some "hello world" examples that show the screaming fast performance of the futures and mio stack

Why Futures?

A major missing piece of the Rust ecosystem has been how to work with Asynchronous I/O and in general composing many I/O tasks together in a lightweight way across libraries. Futures have worked out fantastically in other languages to solve this problem in frameworks like finagle and wangle, and they also turn out to be a great way to solve this problem in Rust as well!

The purpose of the futures library in this repository is to provide the foundational layer to build an ecosystem of futures-generating computations so they can all compose with one another.

The Future trait

At the heart of this crate is the Future trait, which in true Rust style, is an interface for zero allocation futures. Like iterators in Rust, there are a wide variety of helpful combinators associated with this trait which are also zero allocation and serve as a succinct and powerful way to compose computations on futures.

The Future trait is driven by one method, poll, which allows pulling values out of a future and also getting notified when a future is complete. More documentation can be found on the associated method.

More information can be found in the tutorial

I/O with futures

With the power of zero-allocation futures we can take futures all the way down the stack to the I/O layer. The tokio-core crate provides an abstraction for I/O objects as a stream of readiness notifications plus Read and Write traits along with a number of combinators you'd expect when working with std::io.

These abstractions can be implemented by the with mio to power I/O. Finally we can then use these abstractions to build a tokio-tls crate crate to provide TLS/SSL streams over arbitrary read/write streams. Finally tokio-proto can be layered on top for easily writing highly efficient protocol implementations.

License

futures-rs is primarily distributed under the terms of both the MIT license and the Apache License (Version 2.0), with portions covered by various BSD-like licenses.

See LICENSE-APACHE, and LICENSE-MIT for details.