Add core::future::{poll_fn, PollFn}
This is a sibling PR to #70834, adding `future::poll_fn`. This is a small helper function that helps bridge the gap between "poll state machines" and "async/await". It was first introduced in [futures@0.1.7](https://docs.rs/futures/0.1.7/futures/future/fn.poll_fn.html) in December of 2016, and has been tried and tested as part of the ecosystem for the past 3.5 years.
## Implementation
Much of the same reasoning from #70834 applies: by returning a concrete struct rather than an `async fn` we get to mark the future as `Unpin`. It also becomes named which allows storing it in structs without boxing. This implementation has been modified from the implementation in `futures-rs`.
## References
- [`futures::future::poll_fn`](https://docs.rs/futures/0.3.5/futures/future/fn.poll_fn.html)
- [`async_std::future::poll_fn`](https://docs.rs/async-std/1.5.0/async_std/future/fn.poll_fn.html)
Fixes#69446
When we encounter a region error involving an `FnMut` closure, we
display a specialized error message. However, we currently do not
tell the user which upvar was captured. This makes it difficult to
determine the cause of the error, especially when the closure is large.
This commit records marks constraints involving closure upvars
with `ConstraintCategory::ClosureUpvar`. When we decide to 'blame'
a `ConstraintCategory::Return`, we additionall store
the captured upvar if we found a `ConstraintCategory::ClosureUpvar` in
the path.
When generating an error message, we point to relevant spans if we have
closure upvar information available. We further customize the message if
an `async` closure is being returned, to make it clear that the captured
variable is being returned indirectly.
This patch adds `core::future::IntoFuture`. However unlike earlier PRs this patch does not integrate it into the `async/.await` lowering. That integration should be done in a follow-up PR.
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)
Fixed outdated reference to `waker` argument; now futures are passed a
`Context`, from which one can obtain a `waker`.
Cleaned up explanation of what happens when you call `poll` on a completed
future. It doesn't make sense to say that `poll` implementations can't cause
memory unsafety; no safe function is ever allowed to cause memory unsafety, so
why mention it here? It seems like the intent is to say that the `Future` trait
doesn't say what the consequences of excess polls will be, and they might be
bad; but that the usual constraints that Rust imposes on any non-`unsafe`
function still apply. It's also oddly specific to say 'memory corruption'
instead of just 'undefined behavior'; UB is a bit jargony, so the text should
provide examples.
Fix typo in std::future::Future docs
I am not quite sure if this is actually a typo but
1. to me the sentence doesn't make sense if it says "expect"
2. I hope that `Future`s are not really allowed to cause memory unsafety if they are polled after completion.
There are two big categories of changes in here
- Removing lifetimes from common traits that can essentially never user a lifetime from an input (particularly `Drop` & `Debug`)
- Forwarding impls that are only possible because the lifetime doesn't matter (like `impl<R: Read + ?Sized> Read for &mut R`)
I omitted things that seemed like they could be more controversial, like the handful of iterators that have a `Item: 'static` despite the iterator having a lifetime or the `PartialEq` implementations where the flipped one cannot elide the lifetime.
This change updates the future and task API as discussed in the stabilization RFC at https://github.com/rust-lang/rfcs/pull/2592.
Changes:
- Replacing UnsafeWake with RawWaker and RawWakerVtable
- Removal of LocalWaker
- Removal of Arc-based Wake trait
Remove pin::Unpin reexport and add Unpin to the prelude.
Change Pin associated functions to methods.
Rename get_mut_unchecked_ to get_unchecked_mut
Remove impl Unpin for Pin
Mark Pin repr(transparent)
