62374ee4ad
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)
|
||
|---|---|---|
| .. | ||
| bootstrap | ||
| build_helper | ||
| ci | ||
| doc | ||
| etc | ||
| liballoc | ||
| libarena | ||
| libcore | ||
| libfmt_macros | ||
| libgraphviz | ||
| libpanic_abort | ||
| libpanic_unwind | ||
| libproc_macro | ||
| libprofiler_builtins | ||
| librustc_apfloat | ||
| librustc_ast | ||
| librustc_ast_lowering | ||
| librustc_ast_passes | ||
| librustc_ast_pretty | ||
| librustc_attr | ||
| librustc_builtin_macros | ||
| librustc_codegen_llvm | ||
| librustc_codegen_ssa | ||
| librustc_data_structures | ||
| librustc_driver | ||
| librustc_error_codes | ||
| librustc_errors | ||
| librustc_expand | ||
| librustc_feature | ||
| librustc_fs_util | ||
| librustc_hir | ||
| librustc_hir_pretty | ||
| librustc_incremental | ||
| librustc_index | ||
| librustc_infer | ||
| librustc_interface | ||
| librustc_lexer | ||
| librustc_lint | ||
| librustc_llvm | ||
| librustc_macros | ||
| librustc_metadata | ||
| librustc_middle | ||
| librustc_mir | ||
| librustc_mir_build | ||
| librustc_parse | ||
| librustc_passes | ||
| librustc_plugin_impl | ||
| librustc_privacy | ||
| librustc_query_system | ||
| librustc_resolve | ||
| librustc_save_analysis | ||
| librustc_session | ||
| librustc_span | ||
| librustc_symbol_mangling | ||
| librustc_target | ||
| librustc_trait_selection | ||
| librustc_traits | ||
| librustc_ty | ||
| librustc_typeck | ||
| librustdoc | ||
| libserialize | ||
| libstd | ||
| libterm | ||
| libtest | ||
| libunwind | ||
| llvm-project@3ba91917e5 | ||
| rtstartup | ||
| rustc | ||
| rustllvm | ||
| stdarch@d10eefc622 | ||
| test | ||
| tools | ||
| README.md | ||
| stage0.txt | ||
This directory contains the source code of the rust project, including:
rustcand its testslibstd- Various submodules for tools, like rustdoc, rls, etc.
For more information on how various parts of the compiler work, see the rustc dev guide.