Gotchas

[rylev]

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.

[carllerche]

Do you have thoughts about where this would fit in the outline?

[emschwartz]

In this vein:

• Futures really don't do anything unless you make sure they've been picked up by the executor and it's set to drive them to completion. I read about the polling model but didn't grok it until I spent a couple hours scratching my head about why a stream processed one event and then stopped. It might be worth trying to give an example that would look to someone unfamiliar with Tokio like it should work but that doesn't run and use that to explain the subtle ways you can get this wrong.
• This is a subtle but super important point: 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 helpful

Generally, 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".

[emschwartz]

@carllerche I could see this being in a Troubleshooting section at the end

[rylev]

As @emschwartz suggests, I think having a dedicated troubleshooting/gotchas/FAQ section would be helpful.