1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
// \ O /
// / * \ aiur: the home planet for the famous executors
// |' | '| (c) 2020 - present, Vladimir Zvezda
// / \
/// Pins the stack variable.
///
/// Macro makes the stack variable provided as argument to be the type of `std::pin::Pin<&mut T>`.
/// ```
/// # use core::pin::Pin;
/// # use aiur::pin_local;
/// # struct Context { }
/// # let ctx = Context {};
/// # struct MyFuture { };
/// # impl MyFuture {
/// # fn poll(self: Pin<&mut Self>, ctx: Context) -> u32 { 42 }
/// # }
/// // MyFuture implements std::future::Future
/// let fut = MyFuture { /*..*/ };
/// // let _ = fut.poll(ctx); cannot do this as poll requires pinned value
/// pin_local!(fut);
/// // Now we can invoke poll because the type of `fut` now is `std::pin::Pin<&mut MyFuture>`
/// let _ = fut.poll(ctx);
/// ```
///
/// Internally it just shadows the original variable with pinned pointer:
/// ```
/// # let mut var_name = 42;
/// let mut var_name = unsafe { core::pin::Pin::new_unchecked(&mut var_name) };
/// ```
/// As original value is shadowed, there is no both pin and unpin references of the same data
/// exist which justifies the usage of unsafe is ok.
///
/// The similar macro exists in other crates, e.g. `pin_mut!()` in pin-utils or `pin!()` in tokio.