1 #![stable(feature = "futures_api", since = "1.36.0")]
3 //! Asynchronous basic functionality.
5 //! Please see the fundamental [`async`] and [`await`] keywords and the [async book]
6 //! for more information on asynchronous programming in Rust.
8 //! [`async`]: ../../std/keyword.async.html
9 //! [`await`]: ../../std/keyword.await.html
10 //! [async book]: https://rust-lang.github.io/async-book/
13 ops::{Generator, GeneratorState},
16 task::{Context, Poll},
26 #[stable(feature = "futures_api", since = "1.36.0")]
27 pub use self::future::Future;
29 #[unstable(feature = "future_join", issue = "91642")]
30 pub use self::join::join;
32 #[stable(feature = "into_future", since = "1.64.0")]
33 pub use into_future::IntoFuture;
35 #[stable(feature = "future_readiness_fns", since = "1.48.0")]
36 pub use pending::{pending, Pending};
37 #[stable(feature = "future_readiness_fns", since = "1.48.0")]
38 pub use ready::{ready, Ready};
40 #[stable(feature = "future_poll_fn", since = "1.64.0")]
41 pub use poll_fn::{poll_fn, PollFn};
43 /// This type is needed because:
45 /// a) Generators cannot implement `for<'a, 'b> Generator<&'a mut Context<'b>>`, so we need to pass
46 /// a raw pointer (see <https://github.com/rust-lang/rust/issues/68923>).
47 /// b) Raw pointers and `NonNull` aren't `Send` or `Sync`, so that would make every single future
48 /// non-Send/Sync as well, and we don't want that.
50 /// It also simplifies the HIR lowering of `.await`.
52 #[unstable(feature = "gen_future", issue = "50547")]
53 #[derive(Debug, Copy, Clone)]
54 pub struct ResumeTy(NonNull<Context<'static>>);
56 #[unstable(feature = "gen_future", issue = "50547")]
57 unsafe impl Send for ResumeTy {}
59 #[unstable(feature = "gen_future", issue = "50547")]
60 unsafe impl Sync for ResumeTy {}
62 /// Wrap a generator in a future.
64 /// This function returns a `GenFuture` underneath, but hides it in `impl Trait` to give
65 /// better error messages (`impl Future` rather than `GenFuture<[closure.....]>`).
66 // This is `const` to avoid extra errors after we recover from `const async fn`
67 #[lang = "from_generator"]
69 #[unstable(feature = "gen_future", issue = "50547")]
70 #[rustc_const_unstable(feature = "gen_future", issue = "50547")]
72 pub const fn from_generator<T>(gen: T) -> impl Future<Output = T::Return>
74 T: Generator<ResumeTy, Yield = ()>,
76 #[rustc_diagnostic_item = "gen_future"]
77 struct GenFuture<T: Generator<ResumeTy, Yield = ()>>(T);
79 // We rely on the fact that async/await futures are immovable in order to create
80 // self-referential borrows in the underlying generator.
81 impl<T: Generator<ResumeTy, Yield = ()>> !Unpin for GenFuture<T> {}
83 impl<T: Generator<ResumeTy, Yield = ()>> Future for GenFuture<T> {
84 type Output = T::Return;
86 fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Self::Output> {
87 // SAFETY: Safe because we're !Unpin + !Drop, and this is just a field projection.
88 let gen = unsafe { Pin::map_unchecked_mut(self, |s| &mut s.0) };
90 // Resume the generator, turning the `&mut Context` into a `NonNull` raw pointer. The
91 // `.await` lowering will safely cast that back to a `&mut Context`.
92 match gen.resume(ResumeTy(NonNull::from(cx).cast::<Context<'static>>())) {
93 GeneratorState::Yielded(()) => Poll::Pending,
94 GeneratorState::Complete(x) => Poll::Ready(x),
102 #[lang = "get_context"]
104 #[unstable(feature = "gen_future", issue = "50547")]
107 pub unsafe fn get_context<'a, 'b>(cx: ResumeTy) -> &'a mut Context<'b> {
108 // SAFETY: the caller must guarantee that `cx.0` is a valid pointer
109 // that fulfills all the requirements for a mutable reference.
110 unsafe { &mut *cx.0.as_ptr().cast() }