Open rylev opened 5 years ago
Do you have thoughts about where this would fit in the outline?
In this vein:
Any function that returns Async must adhere to the contract. When NotReady is returned, the current task must have been registered for notification on readiness change.
It's really annoying to debug this issue if you return Async::NotReady in the wrong way (It might be worth having a Troubleshooting section to give some tips on unsticking yourself without needing to ask in the Tokio Gitter -- things like running the program with RUST_LOG=trace and if you see the last thing being the event loop going to sleep checking if you're returning Async::NotReady in the wrong way somewhere). The example in the Runtime Model guide that explains adding a loop to solve this issue was really helpfulGenerally, it would be good to have a section like this organized by what issue you might be seeing and what some likely causes are, for example "a stream combinator executes once and then hangs", or "the future stops and the RUST_LOG=trace shows an event added to the tokio loop".
@carllerche I could see this being in a Troubleshooting section at the end
As @emschwartz suggests, I think having a dedicated troubleshooting/gotchas/FAQ section would be helpful.
Having a section on "gotchas" or trouble shooting will be important. Most issues people run into with Tokio probably come down to 3-5 different problems. Having go-to explanations of these will help.
One specific set of gotchas around Tokio is the use of impl Future and lifetimes. There are issues with the borrow checker that users who have written a fair amount of Rust may encounter for the first time when using Futures. Having a section that talks through some subtleties even if they aren't really specific to Tokio would be good.