Pre-RFC Futures/Tokio Cookbook

#1

Cross-Posting from this GH ticket : https://github.com/tokio-rs/tokio/issues/86

Intent

The deliverable of this ticket will be a fairly complete list of topics for v1 of a Tokio and Futures cookbook, as well as a document structure and design guideline for ongoing additions. The finished product is intended to address the cookbook part of #13.

In addition to fielding and refining topics, there is a question of the actual structure of the topics as well. This is because many of the topics have valid solutions as compositions of combinators, or as implementations as futures traits (or both).

Also, at the high level, I’d like to come up with heuristics for the size and scope of what is considered a ‘recipe’ as many of these might exceed those, and could be broken down into sub-recipes.

Format

The plan is to plagiarize the structure and format of the existing Rust Cookbook

Hosting

This effort does not propose an actual hosting location. It is hoped that it will live either as a subcategory of the existing tokio documentation site, or under a Futures topic of the Rust Cookbook.

Topics

Common Tasks

  1. Starting and stopping the reactor core.
  2. Interacting with async interfaces that don’t have an FD
    1. Polling resources (e.g. hardware pins, etc)
    2. Callback APIs
    3. Non-blocking APIs (try_*, etc)
  3. Running multiple reactors/execs in multiple threads.
  4. Running 1 reactor/exec in multiple threads.
  5. Sending to futures from blocking/sync threads.
  6. Receiving from futures in blocking/sync threads.

Managing Monomorphization (need a better name)

  1. Returning multiple error types from a function
  2. Returning multiple futures/streams types but with the same Item
    1. (from match/if let)
  3. A workflow that might produce one of several futures based on some conditional

Standard Protocols

  1. http 1 and 2.0 client basic request response
  2. http 1.1 and 2.0 server - basic RESTful style
  3. Database read/write
  4. TLS / APN
  5. ASIO? (not common, but interesting)

Advanced networking

  1. (client or server) streams of data that reconnect semi-transparently.
  2. Managing connections with out of band data (separating ping/heartbeats)
#2

Hi @rrichardson cookbook maintainer here.
Cool idea. Actually we have a plan to add an async chapter to the cookbook once the rust async story matures a bit (and tokio finishes its API reform).

#3

Glad to hear it. I am embarking on this with the full understanding that most of the examples will have to be tweaked a bit once the API changes land. I’m happy to contribute to the cookbook in whatever way is the most helpful.

#4

@rrichardson Sorry for late reply. I’m more than a little tied recently but I’d be glad to receive any and all PRs to the cookbook or we can merge the tokyo cookbook as a separate chapter at later date if you’ll feel like it!

Please note that cookbook form is likely to be reorganized in the upcoming future