futures-rs

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

Documentation

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!

What's in this project

This repository currently houses a number of futures-related crates, all with associated documentation:

• futures - the core abstraction of zero-cost futures
• futures-io - core zero-cost I/O abstractions expressed with futures and streams
• futures-mio - a concrete implementation of TCP/UDP futures-io abstractions backed by mio
• futures-socks5 - an implementation of an efficient SOCKSv5 proxy server showcasing futures, futures-io, and futures-mio
• futures-tls - TLS/SSL streams built on futures-io abstractions implementing both client and server side connections, with support for the native system library on all platforms
• futures-cpupool - a thread pool for compute-bound work in event loops
• futures-minihttp - a simple HTTP server with some "hello world" examples that show the screaming fast performance of the futures and mio stack
• tls-example - an HTTP server, built with minihttp, which accepts TLS connections, currently this demo requires OpenSSL

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 the 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 two methods, poll and schedule, which allow pulling values out of a future and otherwise getting notified when a future is complete. More documentation can be found on the associated methods themselves.

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 futures-io 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 futures-mio crate to use mio to power I/O. Finally we can then use these abstractions to build a futures-tls crate crate to provide TLS/SSL streams over arbitrary read/write streams.

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.