Aaron Turon     Archive     Feed

Expanding the Tokio project

If you’ve been following Rust in the last month, you’ve probably seen the announcements of the Futures library and the Tokio framework that sits on top of it. There’s been some confusion about how these projects fit together, and what the overall story is shaping up to be.

Today, we’re happy to announce the formation of the Tokio Core Team, as well as an overall plan for the two projects and how they fit together. The team consists of Carl Lerche, Alex Crichton, and myself; more on that below.

An early vision of the I/O stack

There are three primary levels of abstraction in Tokio:


At the highest level is a service, which is where you write a server application. Following the Finagle model, a service is a simple thing: it’s a function from requests to futures of responses. This simple model is incredibly powerful: it separates the implementation of request processing from the implementation of the underlying protocol, and makes it possible to factor out an ecosystem of middleware. All of this seamlessly support async I/O via futures. Middleware runs the gamut from connection pooling to retry/timeout logic to logging to load balancing – all of which can be written independently from any particular service or protocol. Read Your Server as a Function for the inspiration.

The tokio-service crate provides core trait definitions for services. Servers that can process particular request/response types (like HTTP) are offered as standalone crates. Building an http server is just a matter of writing a function from http requests to futures of http responses.


In the middle are protocols, like HTTP or Mux. Here, too, there is a lot of complexity worth factoring out, both at the transport layer and in the protocol “dispatch” layer. The tokio-proto crate provides re-usable components for building new protocol implementations. We expect for there to be a similar kind of “middleware” ecosystem at these lower levels.

Event loop

At the lowest level is the event loop, which is where we bridge the OS’s I/O facilities into the world of futures. The tokio-core crate provides a generic event loop for doing async I/O with futures. If you want complete control, that’s the entry point for you; it’s particularly useful for cases that don’t fit so nicely into the service model, such as proxy servers.

The stack as a whole

In short, we want the Tokio project to be a “one stop shop” for doing futures-based I/O, whether at the highest level of prebuilt protocols, or the lowest level of the core event loop.

In our view, the lowest layers should strive to be zero cost and fully general, allowing them to be used in a large number of contexts. As you go up the stack, getting closer to an actual application, things tend to get more specific and opinionated, and may impose some cost. Futures themselves are a zero-cost and very general abstraction in Rust, and the tokio-core crate imposes very little cost. Particular protocol implementations and middleware, on the other hand, can be more opinionated.

We’ll have a lot more to say about all of these layers (and the ones beneath them, like futures) in the coming weeks on our various blogs. Stay tuned!

A note on project management

We’re following a Rust-like model, starting with a core team that reaches major decisions through a consensus process. At the moment, this process is fairly informal: it plays out on the issue tracker, PRs, and gitter channels. But as the library begins to mature, we plan to move toward an RFC-like process for major changes. We are eager for the Tokio project to truly be a Rust community project. It’s going to have a lot of stakeholders, and we want to make sure those stakeholders have a voice just as we do in the Rust project itself.

As for the core futures library, it remains separate from the Tokio project, in part because we imagine it heading toward ownership by the rust-lang org in the relatively near future. (That’s a possible eventual path for Tokio as well, but the road will be much longer.)

Jumping in

Tokio is an ambitious project, and it’s going to take a strong community to really get it off the ground. Many from the Rust community have already jumped in to contribute, even in these extremely early days; that’s helped us get some of our early-stage integrations going, including curl, tls and redis. We’re also working with Sean McArthur to get a Tokio-integrated Hyper off the ground. If you’re interested in any of this, any other integrations, or the core libraries, we’d love to hear from you!

If you’re coming to RustConf, we’ll see you there, either at the Tokio hack night or at the talk about futures at RustConf itself. Come say hello, and join in the fun!