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 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
futures-curl - an asynchronous HTTP client backed by libcurl exposed through futures

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.

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 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.

alexcrichton / futures-rs