Initial skeleton of the cookbook

.gitignore

@@ -0,0 +1 @@
+cookbook/book/

cookbook/README.md

@@ -0,0 +1,11 @@
+This folder contains the source for the tokio cookbook, in mdbook format.
+
+*Note*: This file just documents this folder and isn't part of the book itself.
+
+To build the book, first install mdbook:
+
+    cargo install mdbook
+
+And then build it:
+
+    mdbook build

cookbook/book.toml

@@ -0,0 +1,5 @@
+[book]
+title = "Tokio Cookbook"
+description = "Collection of useful and common patterns for tokio"
+authors = ["Tokio Community"]
+src = "src"

cookbook/src/SUMMARY.md

@@ -0,0 +1,11 @@
+# Summary
+
+[About](about.md)
+- [Application structure](application-structure.md)
+- [Concurrency](concurrency.md)
+- [File system](file-system.md)
+- [Futures, Streams, Sinks](futures-streams-sinks.md)
+- [Networkings](networking.md)
+- [Operating System](operating-system.md)
+- [Time](time.md)
+- [Transports](transports.md)

cookbook/src/about.md

@@ -0,0 +1,6 @@
+# About
+
+A collection of simple examples that demonstrate good practices to accomplish
+common tasks with Tokio.
+
+[Discussion](https://github.com/tokio-rs/doc-push/issues/23)

cookbook/src/application-structure.md

@@ -0,0 +1,37 @@
+# Application structure
+
+## Background tasks
+
+This shows how to spawn a task to perform work in the background. For example,
+updating configuration on an interval.
+
+How is the task shutdown when the application is shutdown.
+
+## Shutting down an application
+
+How to signal to an application to shutdown.
+
+* Listen for `ctrl-c`
+* Gracefully shutdown open sockets
+* Background tasks shutdown
+* Setting a timeout
+
+## Managing state between tasks with message passing
+
+An actor like pattern is used a lot with Tokio applications.
+
+When there is a resource or state that needs to be accessed from many tasks, one
+way to handle this is to spawn a task dedicated to managing that resource. Then,
+all other tasks interact with the state via message passing.
+
+This section probably can use multiple cookbook examples.
+
+* Mutating a hashmap
+* Managing a transport (see [here](https://github.com/tokio-rs/tokio/issues/86#issuecomment-358108788))
+
+## Performing CPU intensive operations
+
+This cannot be done from the event loop and must be run on a thread pool
+somehow.
+
+

cookbook/src/concurrency.md

@@ -0,0 +1,4 @@
+# Concurrency
+
+TODO
+

cookbook/src/file-system.md

@@ -0,0 +1,6 @@
+# File system
+
+## Send the contents of a file via a `TcpStream`.
+
+How should this be done?
+

cookbook/src/futures-streams-sinks.md

@@ -0,0 +1,17 @@
+# Futures, Streams, Sinks
+
+## Returning different future types from different branches.
+
+* Box
+* `Either`
+
+## Process events from multiple sources
+
+See
+[here](https://github.com/tokio-rs/doc-push/issues/23#issuecomment-426481892)
+and [here](https://github.com/tokio-rs/tokio/issues/86#issuecomment-358186680).
+
+> What's the pattern for taking "events" from multiple sources and handling them
+> all in the same handler? For example, waiting for network data, waiting for
+> keyboard input, and a timer?
+

cookbook/src/networking.md

@@ -0,0 +1,7 @@
+# Networking
+
+## Connect a `TcpStream` by hostname (DNS).
+
+How should this be done?
+
+and automatically send a message via the `Sink` half.

cookbook/src/operating-system.md

@@ -0,0 +1,19 @@
+# Operating System
+
+Most of the items from [Rust's
+cookbook](https://rust-lang-nursery.github.io/rust-cookbook/intro.html#operating-system)
+applies here.
+
+## Reading from STDIN
+
+TODO
+
+## Writing to STDOUT
+
+While `println` could work, this can block. What is the safe way to do this from
+Tokio?
+
+## Child processes
+
+How to spawn & manage child processes from Tokio?
+

cookbook/src/time.md

@@ -0,0 +1,11 @@
+# Time
+
+## Send a UDP packet every 5 seconds
+
+Combo interval and networking. See [here](https://github.com/tokio-rs/doc-push/issues/23#issuecomment-426477390)
+
+## Limit a Stream by total duration
+
+Terminate a stream when 30 seconds has elapsed. Then show how the number of
+messages can be capped as well by using `take`
+

cookbook/src/transports.md

@@ -0,0 +1,6 @@
+# Transports
+
+## Transparently send message when error is received on `Stream`
+
+This is a form of automatic error handling at the transport level. Implement a
+transport decorator that intercepts errors on the `Stream` half of a certain kind

outline/README.md

@@ -97,7 +97,7 @@ A set of guides showing how to use Tokio in different contexts:
 A collection of simple examples that demonstrate good practices to accomplish
 common tasks with Tokio.
 
-[Details](cookbook.md)
+[Details](../cookbook/src/about.md)
 
 <a name="internals"></a>
 # Internals

outline/overview.md

@@ -1,7 +1,7 @@
-Covers the very basics of what Tokio is, what it's used for and important facts on its usage and performance.
-
-# Guide:
-
-[Overview](https://tokio.rs/docs/overview/)
-
+Covers the very basics of what Tokio is, what it's used for and important facts on its usage and performance.
+
+# Guide:
+
+[Overview](https://tokio.rs/docs/overview/)
+
 # Issues