RFC: Let's deprecate wait

[rushmorem]

It's too easy to use incorrectly

I have seen a lot of people, myself included, use it incorrectly either out of ignorance or just because it's so convenient to use (sometimes both) ending up with code that block the entire thread unnecessarily. IMHO, the situation has just gotten worse with async/await. People who don't understand the difference between wait() and await!() might use wait() in the async macro (probably because it makes code easier to read) which will work. They will wonder why their programs are slow (it blocks the entire event loop), worse still they might not even realise this.

It makes task execution confusing

According to the documentation we have 3 methods of executing futures; wait(), the thread pool and the event loop. I have seen some people get confused about when to use which. The documentation tries to explain this but the fact that the thread pool returns a future and that all futures have a wait method doesn't help. If we deprecate wait() we remain with only 2, the thread pool and the event loop. However, considering that the thread pool simply returns a future, we will be forced to run that future on the event loop which brings us down to only one way to drive futures to completion.

Questions that have also come up include

• when to use the thread pool
• when to use the event loop
• how to use both

In my experience there is only one ideal way to drive futures to completion. That is, using an event loop. If you have tasks that are CPU bound, throw them on the thread pool and grab the CPU futures you get back. If you have tasks that are IO bound construct them as needed and grab the IO futures you get back. Multiplex your CPU futures with your IO futures as needed (you can join, select them etc, all that good stuff) and grab the resulting future. Throw that resulting future on the event loop and you are done. In my experience, this is the most efficient way to use futures and deprecating wait() helps guide users towards this.

It's easy to implement

Those who really need it can easily implement it on top of await().

/cc @alexcrichton

[alexcrichton]

I think this is moreso an issue for the futures crate itself rather than the futures-await crate, but I believe there's a whole slew of reasons to deprecate the Future::wait method at this point, so it's likely to happen regardless

[rushmorem]

You are right. The original RFC was also proposing to make await!() a method that's why I had created that issue here, however, I should have created this issue in the futures crate. Would you like me to move it over there?

[alexcrichton]

Sure!

[rushmorem]

Done. See rust-lang/futures-rs#571.