futures_util: Add a poll_future function

[fogti]

original issue: smol-rs/smol#157

/// Pins a future and then polls it.
fn poll_future<T>(cx: &mut Context<'_>, fut: impl Future<Output = T>) -> Poll<T> {
    futures_util::pin_mut!(fut);
    fut.poll(cx)
}

This function is really useful in providing a bridge between simple async functions and poll_* methods; but appropriate documentation would need to be added, because it has the limitation that all state of the Future, which is only saved in the Future itself, and not via &mut bindings / etc., is lost after each yield, and the async fn should be designed to handle that case (e.g. be reentrant without strict dependency on local state; caching is ok, but external state shouldn't be corrupted if the Future yields and resets).

[Pauan]

That function would only allow you to poll the Future one time. What is the use case for that?

[fogti]

Usage example: https://github.com/YZITE/encsess2/blob/ca0d4e961289328a2ac08acd0fc2f19dc4acd453/lib/src/packet_stream.rs

The most common use is either: as syntactic sugar for implementing poll_* methods, or to reuse async fn's both in the normal public API of a struct and in the poll_* impl.

Another usage example is: https://github.com/stjepang/smol/blob/master/src/async_io.rs

[fogti]

Thus, the general use case is: avoiding code duplication and sometimes easier readable code.

[taiki-e]

the async fn should be designed to handle that case (e.g. be reentrant without strict dependency on local state; caching is ok, but external state shouldn't be corrupted if the Future yields and resets).

This rule also applied recursively to all futures that .await-ed in that async fn, right? If so, it seems not easy to use this as a bridge properly.

[fogti]

Yes, thats right. I have worked a bit with it and noticed that it probably is a rather niche and low-level functionality. It also seems to have a noticable size + performance overhead compared to implementing a poll function directly.

[taiki-e]

I have not investigated the exact cause, but performance issues may be related to that a new future being created, moved, and destructed each time polled. FYI @stjepang