Related to Reddit "Tokio ? Why is it so confusing"

[goriunov]

After opening a Reddit Post i have noticed a nice comment to propose the docs problems.

This is kinda my opinion :)

The main problem i have found is not enough examples from different aspects of Tokio, i can find standard example where we use tasks and i was not able to find any properly working example with not using task but going more low level. The docs on official website explain well but do not provide proper solid examples on which i could test and compare things.

For example i would like to see futures example only and tokio example only as a separate things explaining how tokio improves futures and what does it make easier. (would be also cool if i could execute each of them and test play around). Also as a good thing would be to have few examples compare low level tokio and high level tokio where i could also check what do i achieve by using low level things with direct Future usage against of wrappers from tokio.

The compassing is probably the easiest way to learn things.

Also as a proposal would be cool to have level of difficulty for examples. Which would increase from step to step to see different features and no why is that there .

I know some points may be completely wrong (as i am still in the state of understanding, learning tokio and how future works and it is a bit hard).

[carllerche]

Thanks for your thoughts. I agree that there can be more docs / examples. I am going to try collecting some of my own thoughts and put together a more organized doc push later this week. I will cc this issue.

[goriunov]

Thanks, waiting for new docs :)

[icefoxen]

A few concrete suggestions, both from me and also gathered from the aforementioned reddit thread:

• Given that lots of people know Stuff Is Changing With Futures And Async And Stuff, but nobody knows where it's going to end up or when, a roadmap would be really nice. What does the Tokio team expect things to look like in a year? Two years? Five years? ??Ten?? How does this relate to async/await, the futures crate, etc? Where is tokio, as a whole, going? And what might it look like when it gets there?
• There is not enough documentation on how everything fits together. https://tokio.rs/docs/getting-started/runtime-model/ and the following couple pages are the closest I can find but is fairly brief and high-level. Needs to have at least one srs talk about what is going on down in the guts for the people who know how epoll etc. work and need to see how tokio connects the dots. The more advanced docs in general talk a lot (well, a bit) about what you can do, but not when or why you would want to.
• There needs to be a guide that both does several complete trivial examples, and one non-trivial project. This is a large undertaking!
• There are many examples that are well commented, but they mostly do about the same thing, deal with a single message->response protocol that doesn't need to store much data or do any state-machine-like stuff. Since network protocols tend to be modeled as state machines, and state machines are a PITA in the best case, that's a large oversight.
• The heavy reliance on type inference and complex compose-y-ness of the generics means rustc's error messages suck for tokio programs. A brief document talking about the more common error types and where to look for starting to resolve them would be great!
• In general, tokio's zero-cost abstractions are not zero-cost to the programmer. This one I don't really have a suggestion for. But Box isn't fundamentally evil, especially in the not-uncommon case where to get anything done a user will have to Rc some state to share between futures anyway. The zero-runtime-overhead is the very purpose of tokio's API, however, and is fundamental to its design. Maybe there's a way to show users times and places where a bit of run-time cost can smooth out a lot of the thorns of async I/O in general though? Or a higher-level API that can offer 90% of the capability with 25% the friction?
• People tend to write various blog posts and talks and such about using tokio or futures; aggregating the good ones somewhere might be useful. (With dates, so it's obvious when something may be horribly out of date.)

[Darksonn]

Skimming this, at least some of the stuff seems to maybe be still relevant to the new guides.

[carllerche]

@Darksonn if there are still items to cover, could you open new issues for those specific items and reference this?

[Toerktumlare]

I just did the "getting started" section of the Tokio documentation and i must say that the tutorial of building mini-redis, and later on a mini-tokio was very, very, very confusing.

You start out by building mini-redis, but you borrow types from the library mini-redis, and replace some parts, then suddenly you have to backtrack and remove the borrowed parts because you are then going to replace them with your own parts which makes things even more confusing.

Every now and then the tutorial tells you that you can check out the source code, which i did, and then you find a bunch of things that are not included in the tutorial, which makes things even more confusing.

But the most confusing part is that somewhere along the way, you stop implementing mini-redis, and implement other things, that you have no idea where it should be in your project, and you have no idea if mini-redis was completed or not, and then suddenly we go back to mini-redis and you have no idea what that side step was for.

Then when you start building mini-tokio, you start out by building a version of it, that you then are supposed to rewrite, and you have to add some 3rd party futures crate, and then you have to sort of delete what you have written, which makes the entire thing so strange because you go pack and forth with code that compiles, and code that doesn't compile and you never get any instruction during the implementation of mini-tokio, to even run the code to test the code out.

I have programmed in async in several different languages like javascript, C#, java reactive etc, so i have a fundamental understanding of it.

But these tutorials were all over the place. I still dont really see even the point with installing mini-redis when i only made like 3-4 calls to it on the cmd.

And then suddenly in the streams chapter we are at it with mini-redis again. Its jumping all over the place.

I would suggest that the tutorial in general should follow more the way of the rust book as in.

• Explain the basic concept
• Make your first async calls
• Build a simple application using async
• Run it
• Explain some more concepts
• How to handle blocking calls?
• select
• Build a new async application using the new concepts some blocking calls, using select! etc
• Run that application
• Explain more advanced concepts
• Build a new application from scratch including some of the more advanced concepts.

Im sorry but i feel more confused than before after i have completed the getting started/tutorial