Add Future::timeout() method

[petrzjunior]

Is your feature request related to a problem? Please describe.
Currently, the code to timeout a Future is

let _ = timeout(Duration::from_secs(3), listener.accept())
    .await
    .expect("timeout")
    .expect("accept failed");

I propose it should be possible to write

let _ = listener.accept()
    .timeout(Duration::from_secs(3))
    .await
    .expect("timeout")
    .expect("accept failed");

This results in cleaner code following the fluent style of writing.

Describe the solution you'd like
I propose adding a Future extension method

fn timeout(self, timeout: Duration) -> Timeout<Self>

Describe alternatives you've considered
The current method timeout(Duration, Future) works, but is less readable.

Additional context
The proposed method used to be in Tokio in the past:

tokio/tokio/src/future.rs

Lines 61 to 66 in 27e5b41

	fn timeout(self, timeout: Duration) -> Timeout<Self>
	where
	Self: Sized,
	{
	Timeout::new(self, timeout)
	}

It got removed in #1774 refactoring.

Similar method is implemented in async_std since 2019 async-rs/async-std#600.

[Darksonn]

We don't currently have any extension traits for futures in Tokio, and I'm somewhat reluctant to add one.

[chris-leach]

@Darksonn can you expand on your reluctance at all? I agree that the postfix interface is more ergonomic, especially when there are several chained method calls before the await, as opposed to after:

timeout(
    Duration::from_secs(1),
    RequestBuilder::new(/*...*/)
        .prepare(/*...*/)
        .check(/*...*/)
        .build(/*...*/)
        .send(/*...*/),
)
    .await
    .wrap_err(/* ... */)?;

vs

RequestBuilder::new(/*...*/)
    .prepare(/*...*/)
    .check(/*...*/)
    .build(/*...*/)
    .send(/*...*/)
    .timeout(Duration::from_secs(1))
    .await
    .wrap_err(/* ... */)?;

[YuanYuYuan]

Also curious about why FutureExt was removed from tokio .

[Darksonn]

We removed FutureExt because we wanted to move away from combinators such as map and so on. Async/await syntax has made those mostly obsolete. If we are to add this, I'd prefer to add it to tokio-util.

[evanrittenhouse]

Feel free to assign this to me, I'll add said extension trait to tokio-util