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
- Starting and stopping the reactor core.
- Interacting with async interfaces that don’t have an FD
- Polling resources (e.g. hardware pins, etc)
- Callback APIs
- Non-blocking APIs (try_*, etc)
- Running multiple reactors/execs in multiple threads.
- Running 1 reactor/exec in multiple threads.
- Sending to futures from blocking/sync threads.
- Receiving from futures in blocking/sync threads.
Managing Monomorphization (need a better name)
- Returning multiple error types from a function
- Returning multiple futures/streams types but with the same Item
- (from match/if let)
- A workflow that might produce one of several futures based on some conditional
Standard Protocols
- http 1 and 2.0 client basic request response
- http 1.1 and 2.0 server - basic RESTful style
- Database read/write
- TLS / APN
- ASIO? (not common, but interesting)
Advanced networking
- (client or server) streams of data that reconnect semi-transparently.
- Managing connections with out of band data (separating ping/heartbeats)