tokio-rs / website-next

Next iteration of the Tokio website.

Tokio Website

The website for the Tokio project. Lives at https://tokio.rs.

Besides containing the content for the website, it also includes crates containing the example code used in the tutorial. These crates can be compiled and ran.

• hello-tokio
• spawning
• shared-state
• channels
• io
  • echo-server-copy
  • echo-server
• mini-tokio

Contributing

Thinking about contributing? Great! This should help you get the website running locally.

Getting Started

The website is built using Next.js paired with the Bulma CSS framework. First, make sure you have NPM installed. Next, start the development server:

npm run dev

Then, open http://localhost:3000.

Resources

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.
• Bulma documentation - learn about Bulma.

License

This project is licensed under the MIT license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Tokio by you, shall be licensed as MIT, without any additional terms or conditions.

website-next's Issues

Async, Future, and Pinning topic

This issue tracks topics to cover on this page. This is not exhaustive and just to track ideas.

• Difference between async fn and Future
• How do generators fit in?
• What is pinning
• What is Unpin.

Link in API docs

The Tokio API docs have a link to https://tokio.rs/docs/overview/. We should avoid breaking this link, perhaps with a redirect.

Handle links into mini-redis

Please see #50 (comment)

Fix or remove back to all libraries link

website-next/components/menu.jsx

Line 64 in 4c518e9

<a>All Libraries</a>

Prepare Tower content

The website should have some tower related content. Ideally some guides from the context of the greater Tokio stack.

For reference, the site mockup: https://www.figma.com/file/MiZNvWiJZizlK4fRxzy9jz/Tokio-Refresh?node-id=1%3A8

IDEs

Apparently CLion needs the following setting to make completion work with Tokio types behind our impl_* macros.

Settings > Languages & Frameworks > Rust > Expand declarative macros: Use experimental engine

Prepare some tracing content

The website should have some tracing related content. Ideally some guides from the context of the greater Tokio stack.

For reference, the site mockup: https://www.figma.com/file/MiZNvWiJZizlK4fRxzy9jz/Tokio-Refresh?node-id=1%3A8

Include note on error message when `move` is left out from `async move {`

Links that are also code

A link such as [`Future`] currently shows up identically to code that is not a link. We should update the css to fix this.

Fix "if not, start here" link

In Prerequisites section.

Pre-launch checklist

Tracking things that need to be done pre-launch

• Merge this repo with website.
• Change links from website-next -> website.
• Redirect https://tokio.rs/docs/overview/ (see: https://docs.netlify.com/routing/redirects/)
• Check for broken links with web crawler.

Topics articles

Articles that we would like in our topics section of the documentation.

• Basic concepts (async/await syntax, spawning, don't block the thread)
• When should you use async/await? (and when should you not?)
• Streams #19
• Channels
• Concurrency (spawn, join!, select!, FuturesUnordered)
• Futures as objects
• Cancellation
• AsyncRead/Write
• Interfacing sync and async code
• Codec
• Building the Runtime explicitly
• Shutting down cleanly (abortable, broadcast channels)
• Locks
• Deep dive/Implementing Future/Stream manually

The first five should probably go first. The remaining are in no particular order.

mini-redis outline proposal

Client

Along with the hello-world guide there should be a guide with the pubsub example, to give the user an idea on how the interaction with the server works on the client side

Server

• Start with TcpListener, explaining accept and spawning a new task for each connection.
• Implement Connection struct, describe the read_frame process and Frame conversion, introduce Bytes crate
• Implement Command struct and from_frame method explaining the Frame to Command parsing
• Add GET variant to Command and implement apply method introducing the internal Db and explaining the decisions behind it's implementation: why it's an Arc<Mutex>, the State and Entry struct's
• implement GET's write_frame and describe the process of writing a Command back to a Frame and writing it on the socket
• Add SET variant to Command enum, the flow is similar to GET, but has the key expiration logic. Guide through it's implementation with tokio's Duration and Notify
• Add PUB variant to Command and implement the Db pubsub behavior bringing up tokio's Broadcast struct
• Add SUB variant to Command, and implement the graceful shutdown notification logic of Server
• Implement the client connection limit handling on the Server.
• Introduce tokio-tracing and instrument the code

Don't collapse tutorial on glossary

The sidebar seems very empty when on the glossary.

Fix "Backpressure and bounded channels" section

Discussion: https://github.com/tokio-rs/website-next/pull/47/files#r443221224

Prepare some Hyper content

The website should have some hyper related content. Ideally some guides from the context of the greater Tokio stack.

For reference, the site mockup: https://www.figma.com/file/MiZNvWiJZizlK4fRxzy9jz/Tokio-Refresh?node-id=1%3A8

Fix front page

The getting started button has a broken link link. The "learn more" link on the runtime stack is also broken, as well as Tokio's docs link in the footer.