Rollup merge of #70834 - yoshuawuyts:future-pending-ready, r=sfackler

Add core::future::{pending,ready}

Adds two future constructors to `core`: `future::ready` and `future::pending`. These functions enable constructing futures of any type that either immediately resolve, or never resolve which is an incredible useful tool when writing documentation.

These functions have prior art in both the `futures` and `async-std` crates. This implementation has been adapted from the `futures` crate.

## Examples

In https://github.com/rust-lang/rust/pull/70817 we propose adding the `ready!` macro. In the example we use an `async fn` which does not return a future that implements `Unpin`, which leads to the use of `unsafe`. Instead had we had `future::ready` available, we could've written the same example without using `unsafe`:

```rust
use core::task::{Context, Poll};
use core::future::{self, Future};
use core::pin::Pin;

pub fn do_poll(cx: &mut Context<'_>) -> Poll<()> {
    let mut fut = future::ready(42_u8);
    let num = ready!(Pin::new(fut).poll(cx));
    // ... use num

    Poll::Ready(())
}
```

## Why future::ready?

Arguably `future::ready` and `async {}` can be considered equivalent. The main differences are that `future::ready` returns a future that implements `Unpin`, and the returned future is a concrete type. This is useful for traits that require a future as an associated type that can sometimes be a no-op ([example](https://docs.rs/http-service/0.4.0/http_service/trait.HttpService.html#associatedtype.ConnectionFuture)).

The final, minor argument is that `future::ready` and `future::pending` form a counterpart to the enum members of `Poll`: `Ready` and `Pending`. These functions form a conceptual bridge between `Poll` and `Future`, and can be used as a useful teaching device.

## References
- [`futures::future::ready`](https://docs.rs/futures/0.3.4/futures/future/fn.ready.html)
- [`futures::future::pending`](https://docs.rs/futures/0.3.4/futures/future/fn.pending.html)
- [`async_std::future::pending`](https://docs.rs/async-std/1.5.0/async_std/future/fn.pending.html)
- [`async_std::future::ready`](https://docs.rs/async-std/1.5.0/async_std/future/fn.ready.html)

0 files changed, 0 insertions, 0 deletions