1#![stable(feature = "futures_api", since = "1.36.0")]
2
3//! Asynchronous basic functionality.
4//!
5//! Please see the fundamental [`async`] and [`await`] keywords and the [async book]
6//! for more information on asynchronous programming in Rust.
7//!
8//! [`async`]: ../../std/keyword.async.html
9//! [`await`]: ../../std/keyword.await.html
10//! [async book]: https://rust-lang.github.io/async-book/
11
12use crate::ptr::NonNull;
13use crate::task::Context;
14
15#[cfg(not(bootstrap))]
16mod async_drop;
17mod future;
18mod into_future;
19mod join;
20mod pending;
21mod poll_fn;
22mod ready;
23
24#[stable(feature = "futures_api", since = "1.36.0")]
25pub use self::future::Future;
26
27#[unstable(feature = "future_join", issue = "91642")]
28pub use self::join::join;
29
30#[stable(feature = "into_future", since = "1.64.0")]
31pub use into_future::IntoFuture;
32
33#[stable(feature = "future_readiness_fns", since = "1.48.0")]
34pub use pending::{pending, Pending};
35#[stable(feature = "future_readiness_fns", since = "1.48.0")]
36pub use ready::{ready, Ready};
37
38#[stable(feature = "future_poll_fn", since = "1.64.0")]
39pub use poll_fn::{poll_fn, PollFn};
40
41#[cfg(not(bootstrap))]
42#[unstable(feature = "async_drop", issue = "none")]
43pub use async_drop::{async_drop, async_drop_in_place, AsyncDrop, AsyncDropInPlace};
44
45/// This type is needed because:
46///
47/// a) Coroutines cannot implement `for<'a, 'b> Coroutine<&'a mut Context<'b>>`, so we need to pass
48/// a raw pointer (see <https://github.com/rust-lang/rust/issues/68923>).
49/// b) Raw pointers and `NonNull` aren't `Send` or `Sync`, so that would make every single future
50/// non-Send/Sync as well, and we don't want that.
51///
52/// It also simplifies the HIR lowering of `.await`.
53#[lang = "ResumeTy"]
54#[doc(hidden)]
55#[unstable(feature = "gen_future", issue = "50547")]
56#[derive(Debug, Copy, Clone)]
57pub struct ResumeTy(NonNull<Context<'static>>);
58
59#[unstable(feature = "gen_future", issue = "50547")]
60unsafe impl Send for ResumeTy {}
61
62#[unstable(feature = "gen_future", issue = "50547")]
63unsafe impl Sync for ResumeTy {}
64
65#[lang = "get_context"]
66#[doc(hidden)]
67#[unstable(feature = "gen_future", issue = "50547")]
68#[must_use]
69#[inline]
70pub unsafe fn get_context<'a, 'b>(cx: ResumeTy) -> &'a mut Context<'b> {
71 // SAFETY: the caller must guarantee that `cx.0` is a valid pointer
72 // that fulfills all the requirements for a mutable reference.
73 unsafe { &mut *cx.0.as_ptr().cast() }
74}
75