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