1 /// A pinned projection of a struct field.
2 ///
3 /// # Safety
4 ///
5 /// To make using this macro safe, three things need to be ensured:
6 /// - If the struct implements [`Drop`], the [`drop`] method is not allowed to
7 ///   move the value of the field.
8 /// - If the struct wants to implement [`Unpin`], it has to do so conditionally:
9 ///   The struct can only implement [`Unpin`] if the field's type is [`Unpin`].
10 /// - The struct must not be `#[repr(packed)]`.
11 ///
12 /// # Example
13 ///
14 /// ```rust
15 /// use pin_utils::unsafe_pinned;
16 /// use std::marker::Unpin;
17 /// use std::pin::Pin;
18 ///
19 /// struct Foo<T> {
20 ///     field: T,
21 /// }
22 ///
23 /// impl<T> Foo<T> {
24 ///     unsafe_pinned!(field: T);
25 ///
26 ///     fn baz(mut self: Pin<&mut Self>) {
27 ///         let _: Pin<&mut T> = self.field(); // Pinned reference to the field
28 ///     }
29 /// }
30 ///
31 /// impl<T: Unpin> Unpin for Foo<T> {} // Conditional Unpin impl
32 /// ```
33 ///
34 /// Note: borrowing the field multiple times requires using `.as_mut()` to
35 /// avoid consuming the `Pin`.
36 ///
37 /// [`Unpin`]: core::marker::Unpin
38 /// [`drop`]: Drop::drop
39 #[macro_export]
40 macro_rules! unsafe_pinned {
41     ($f:tt: $t:ty) => (
42         #[allow(unsafe_code)]
43         fn $f<'__a>(
44             self: $crate::core_reexport::pin::Pin<&'__a mut Self>
45         ) -> $crate::core_reexport::pin::Pin<&'__a mut $t> {
46             unsafe {
47                 $crate::core_reexport::pin::Pin::map_unchecked_mut(
48                     self, |x| &mut x.$f
49                 )
50             }
51         }
52     )
53 }
54 
55 /// An unpinned projection of a struct field.
56 ///
57 /// # Safety
58 ///
59 /// This macro is unsafe because it creates a method that returns a normal
60 /// non-pin reference to the struct field. It is up to the programmer to ensure
61 /// that the contained value can be considered not pinned in the current
62 /// context.
63 ///
64 /// # Example
65 ///
66 /// ```rust
67 /// use pin_utils::unsafe_unpinned;
68 /// use std::pin::Pin;
69 ///
70 /// struct Bar;
71 /// struct Foo {
72 ///     field: Bar,
73 /// }
74 ///
75 /// impl Foo {
76 ///     unsafe_unpinned!(field: Bar);
77 ///
78 ///     fn baz(mut self: Pin<&mut Self>) {
79 ///         let _: &mut Bar = self.field(); // Normal reference to the field
80 ///     }
81 /// }
82 /// ```
83 ///
84 /// Note: borrowing the field multiple times requires using `.as_mut()` to
85 /// avoid consuming the [`Pin`].
86 ///
87 /// [`Pin`]: core::pin::Pin
88 #[macro_export]
89 macro_rules! unsafe_unpinned {
90     ($f:tt: $t:ty) => (
91         #[allow(unsafe_code)]
92         fn $f<'__a>(
93             self: $crate::core_reexport::pin::Pin<&'__a mut Self>
94         ) -> &'__a mut $t {
95             unsafe {
96                 &mut $crate::core_reexport::pin::Pin::get_unchecked_mut(self).$f
97             }
98         }
99     )
100 }
101