1/// Pins a value on the stack.
2///
3/// Calls to `async fn` return anonymous [`Future`] values that are `!Unpin`.
4/// These values must be pinned before they can be polled. Calling `.await` will
5/// handle this, but consumes the future. If it is required to call `.await` on
6/// a `&mut _` reference, the caller is responsible for pinning the future.
7///
8/// Pinning may be done by allocating with [`Box::pin`] or by using the stack
9/// with the `pin!` macro.
10///
11/// The following will **fail to compile**:
12///
13/// ```compile_fail
14/// async fn my_async_fn() {
15/// // async logic here
16/// }
17///
18/// #[tokio::main]
19/// async fn main() {
20/// let mut future = my_async_fn();
21/// (&mut future).await;
22/// }
23/// ```
24///
25/// To make this work requires pinning:
26///
27/// ```
28/// use tokio::pin;
29///
30/// async fn my_async_fn() {
31/// // async logic here
32/// }
33///
34/// #[tokio::main]
35/// async fn main() {
36/// let future = my_async_fn();
37/// pin!(future);
38///
39/// (&mut future).await;
40/// }
41/// ```
42///
43/// Pinning is useful when using `select!` and stream operators that require `T:
44/// Stream + Unpin`.
45///
46/// [`Future`]: trait@std::future::Future
47/// [`Box::pin`]: std::boxed::Box::pin
48///
49/// # Usage
50///
51/// The `pin!` macro takes **identifiers** as arguments. It does **not** work
52/// with expressions.
53///
54/// The following does not compile as an expression is passed to `pin!`.
55///
56/// ```compile_fail
57/// async fn my_async_fn() {
58/// // async logic here
59/// }
60///
61/// #[tokio::main]
62/// async fn main() {
63/// let mut future = pin!(my_async_fn());
64/// (&mut future).await;
65/// }
66/// ```
67///
68/// # Examples
69///
70/// Using with select:
71///
72/// ```
73/// use tokio::{pin, select};
74/// use tokio_stream::{self as stream, StreamExt};
75///
76/// async fn my_async_fn() {
77/// // async logic here
78/// }
79///
80/// #[tokio::main]
81/// async fn main() {
82/// let mut stream = stream::iter(vec![1, 2, 3, 4]);
83///
84/// let future = my_async_fn();
85/// pin!(future);
86///
87/// loop {
88/// select! {
89/// _ = &mut future => {
90/// // Stop looping `future` will be polled after completion
91/// break;
92/// }
93/// Some(val) = stream.next() => {
94/// println!("got value = {}", val);
95/// }
96/// }
97/// }
98/// }
99/// ```
100///
101/// Because assigning to a variable followed by pinning is common, there is also
102/// a variant of the macro that supports doing both in one go.
103///
104/// ```
105/// use tokio::{pin, select};
106///
107/// async fn my_async_fn() {
108/// // async logic here
109/// }
110///
111/// #[tokio::main]
112/// async fn main() {
113/// pin! {
114/// let future1 = my_async_fn();
115/// let future2 = my_async_fn();
116/// }
117///
118/// select! {
119/// _ = &mut future1 => {}
120/// _ = &mut future2 => {}
121/// }
122/// }
123/// ```
124#[macro_export]
125macro_rules! pin {
126 ($($x:ident),*) => { $(
127 // Move the value to ensure that it is owned
128 let mut $x = $x;
129 // Shadow the original binding so that it can't be directly accessed
130 // ever again.
131 #[allow(unused_mut)]
132 let mut $x = unsafe {
133 $crate::macros::support::Pin::new_unchecked(&mut $x)
134 };
135 )* };
136 ($(
137 let $x:ident = $init:expr;
138 )*) => {
139 $(
140 let $x = $init;
141 $crate::pin!($x);
142 )*
143 };
144}
145