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 ] |
125 | macro_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 | |