New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Gotchas #14

Open
rylev opened this Issue Oct 2, 2018 · 4 comments

Comments

Projects
None yet
3 participants
@rylev
Collaborator

rylev commented Oct 2, 2018

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

This comment has been minimized.

Member

carllerche commented Oct 2, 2018

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

@emschwartz

This comment has been minimized.

emschwartz commented Oct 2, 2018

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

This comment has been minimized.

emschwartz commented Oct 2, 2018

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

@rylev

This comment has been minimized.

Collaborator

rylev commented Oct 2, 2018

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

@carllerche carllerche added the guide label Oct 3, 2018

@carllerche carllerche changed the title from Missing Section: Gotchas to Gotchas Oct 3, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment