diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..786bd97 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +cookbook/book/ \ No newline at end of file diff --git a/cookbook/README.md b/cookbook/README.md new file mode 100644 index 0000000..08706a7 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/cookbook/book.toml b/cookbook/book.toml new file mode 100644 index 0000000..33e4a95 --- /dev/null +++ b/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" diff --git a/cookbook/src/SUMMARY.md b/cookbook/src/SUMMARY.md new file mode 100644 index 0000000..f389c53 --- /dev/null +++ b/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) diff --git a/cookbook/src/about.md b/cookbook/src/about.md new file mode 100644 index 0000000..4e2654a --- /dev/null +++ b/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) diff --git a/cookbook/src/application-structure.md b/cookbook/src/application-structure.md new file mode 100644 index 0000000..9df50d8 --- /dev/null +++ b/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. + + diff --git a/cookbook/src/concurrency.md b/cookbook/src/concurrency.md new file mode 100644 index 0000000..648b90f --- /dev/null +++ b/cookbook/src/concurrency.md @@ -0,0 +1,4 @@ +# Concurrency + +TODO + diff --git a/cookbook/src/file-system.md b/cookbook/src/file-system.md new file mode 100644 index 0000000..fbc9b3c --- /dev/null +++ b/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? + diff --git a/cookbook/src/futures-streams-sinks.md b/cookbook/src/futures-streams-sinks.md new file mode 100644 index 0000000..1e99a87 --- /dev/null +++ b/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? + diff --git a/cookbook/src/networking.md b/cookbook/src/networking.md new file mode 100644 index 0000000..8c5a9dd --- /dev/null +++ b/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. \ No newline at end of file diff --git a/cookbook/src/operating-system.md b/cookbook/src/operating-system.md new file mode 100644 index 0000000..f1fc957 --- /dev/null +++ b/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? + diff --git a/cookbook/src/time.md b/cookbook/src/time.md new file mode 100644 index 0000000..3daedf9 --- /dev/null +++ b/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` + diff --git a/cookbook/src/transports.md b/cookbook/src/transports.md new file mode 100644 index 0000000..6d25b1d --- /dev/null +++ b/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 diff --git a/outline/README.md b/outline/README.md index c4afb04..c33282f 100644 --- a/outline/README.md +++ b/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) # Internals diff --git a/outline/cookbook.md b/outline/cookbook.md deleted file mode 100644 index 23cfd9d..0000000 --- a/outline/cookbook.md +++ /dev/null @@ -1,130 +0,0 @@ -This section is still in the brainstorming phase. Most of the existing contents -and categories still need to be refined. - -[Discussion](https://github.com/tokio-rs/doc-push/issues/23) - -# Categories: - -* [Application structure](#structure) -* [Concurrency](#concurrency) -* [File system](#fs) -* [Futures, Streams, Sinks](#futures-streams-sinks) -* [Networking](#networking) -* [Operating System](#os) -* [Time](#time) -* [Transports](#transports) - - -## 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. - - -## Concurrency - -TODO - - -## File system - -#### Send the contents of a file via a `TcpStream`. - -How should this be done? - - -## 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? - - -## Networking - -#### Connect a `TcpStream` by hostname (DNS). - -How should this be done? - - -## 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? - - -## 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` - - -## 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 -and automatically send a message via the `Sink` half. diff --git a/outline/overview.md b/outline/overview.md index 52cafa3..c256f24 100644 --- a/outline/overview.md +++ b/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 \ No newline at end of file