New poll_immediate functions to immediately return from a poll

[tylerhawkes]

I can open an issue as well if needed, but since I've already done the work I thought it would be just as easy to actually talk about the additions proposed in the pull request.

The reasons for these new functions are because I'm using a tokio::sync::mpsc::Receiver and sometimes I need to just wait until a value is ready and sometimes I need to check if one is ready and if not do some other processing. This can be accomplished by doing

    futures_util::select_biased! {
        msg = receiver.recv().await => {...}
        _ = futures_util::future::ready(()) => {...}
    }

but it seems like it would be nice to have a dedicated Future for this that works better with IDE's.

I could probably use the now_or_never() function from FuturesExt, but that consumes the future and these new functions and futures allow for polling repeatedly (due to the Stream implementation) to see if they are done without blocking and they can also get the future back if it is Unpin which is useful if the futures are expensive to construct or if you want to just wait for them to be done at a later time.

Closes #2257

[taiki-e]

Thanks for the PR. Almost all of unsafe code used in this PR is not correct. Please use pin-project-lite as existing code does.

[tylerhawkes]

@taiki-e I think all the checks should pass now, if you can approve the waiting workflow.

[taiki-e]

Some futures expect it will be polled until complete, and such usage may cause problems. (see smol-rs/async-io#37 (comment))
Also, creating futures frequently and then dropping them may cause performance problems. (see #2173)

I am not strongly opposed to adding such features, but I think it would be preferable to mention these issues in the documentation.

[taiki-e]

Thanks. LGTM aside from a nit.

[taiki-e]

Thanks!

[taiki-e]

Published in 0.3.17