tokio/macros/
pin.rs

Help
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}
tokio/macros/pin.rs

tokio/macros/
pin.rs
