1 // SPDX-License-Identifier: Apache-2.0 OR MIT
2 
3 //! This module contains library internal items.
4 //!
5 //! These items must not be used outside of this crate and the pin-init-internal crate located at
6 //! `../internal`.
7 
8 use super::*;
9 
10 /// See the [nomicon] for what subtyping is. See also [this table].
11 ///
12 /// The reason for not using `PhantomData<*mut T>` is that that type never implements [`Send`] and
13 /// [`Sync`]. Hence `fn(*mut T) -> *mut T` is used, as that type always implements them.
14 ///
15 /// [nomicon]: https://doc.rust-lang.org/nomicon/subtyping.html
16 /// [this table]: https://doc.rust-lang.org/nomicon/phantom-data.html#table-of-phantomdata-patterns
17 pub(crate) type Invariant<T> = PhantomData<fn(*mut T) -> *mut T>;
18 
19 /// Module-internal type implementing `PinInit` and `Init`.
20 ///
21 /// It is unsafe to create this type, since the closure needs to fulfill the same safety
22 /// requirement as the `__pinned_init`/`__init` functions.
23 pub(crate) struct InitClosure<F, T: ?Sized, E>(pub(crate) F, pub(crate) Invariant<(E, T)>);
24 
25 // SAFETY: While constructing the `InitClosure`, the user promised that it upholds the
26 // `__init` invariants.
27 unsafe impl<T: ?Sized, F, E> Init<T, E> for InitClosure<F, T, E>
28 where
29     F: FnOnce(*mut T) -> Result<(), E>,
30 {
31     #[inline]
__init(self, slot: *mut T) -> Result<(), E>32     unsafe fn __init(self, slot: *mut T) -> Result<(), E> {
33         (self.0)(slot)
34     }
35 }
36 
37 // SAFETY: While constructing the `InitClosure`, the user promised that it upholds the
38 // `__pinned_init` invariants.
39 unsafe impl<T: ?Sized, F, E> PinInit<T, E> for InitClosure<F, T, E>
40 where
41     F: FnOnce(*mut T) -> Result<(), E>,
42 {
43     #[inline]
__pinned_init(self, slot: *mut T) -> Result<(), E>44     unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> {
45         (self.0)(slot)
46     }
47 }
48 
49 /// This trait is only implemented via the `#[pin_data]` proc-macro. It is used to facilitate
50 /// the pin projections within the initializers.
51 ///
52 /// # Safety
53 ///
54 /// Only the `init` module is allowed to use this trait.
55 pub unsafe trait HasPinData {
56     type PinData: PinData;
57 
58     #[expect(clippy::missing_safety_doc)]
__pin_data() -> Self::PinData59     unsafe fn __pin_data() -> Self::PinData;
60 }
61 
62 /// Marker trait for pinning data of structs.
63 ///
64 /// # Safety
65 ///
66 /// Only the `init` module is allowed to use this trait.
67 pub unsafe trait PinData: Copy {
68     type Datee: ?Sized + HasPinData;
69 
70     /// Type inference helper function.
make_closure<F, O, E>(self, f: F) -> F where F: FnOnce(*mut Self::Datee) -> Result<O, E>,71     fn make_closure<F, O, E>(self, f: F) -> F
72     where
73         F: FnOnce(*mut Self::Datee) -> Result<O, E>,
74     {
75         f
76     }
77 }
78 
79 /// This trait is automatically implemented for every type. It aims to provide the same type
80 /// inference help as `HasPinData`.
81 ///
82 /// # Safety
83 ///
84 /// Only the `init` module is allowed to use this trait.
85 pub unsafe trait HasInitData {
86     type InitData: InitData;
87 
88     #[expect(clippy::missing_safety_doc)]
__init_data() -> Self::InitData89     unsafe fn __init_data() -> Self::InitData;
90 }
91 
92 /// Same function as `PinData`, but for arbitrary data.
93 ///
94 /// # Safety
95 ///
96 /// Only the `init` module is allowed to use this trait.
97 pub unsafe trait InitData: Copy {
98     type Datee: ?Sized + HasInitData;
99 
100     /// Type inference helper function.
make_closure<F, O, E>(self, f: F) -> F where F: FnOnce(*mut Self::Datee) -> Result<O, E>,101     fn make_closure<F, O, E>(self, f: F) -> F
102     where
103         F: FnOnce(*mut Self::Datee) -> Result<O, E>,
104     {
105         f
106     }
107 }
108 
109 pub struct AllData<T: ?Sized>(Invariant<T>);
110 
111 impl<T: ?Sized> Clone for AllData<T> {
clone(&self) -> Self112     fn clone(&self) -> Self {
113         *self
114     }
115 }
116 
117 impl<T: ?Sized> Copy for AllData<T> {}
118 
119 // SAFETY: TODO.
120 unsafe impl<T: ?Sized> InitData for AllData<T> {
121     type Datee = T;
122 }
123 
124 // SAFETY: TODO.
125 unsafe impl<T: ?Sized> HasInitData for T {
126     type InitData = AllData<T>;
127 
__init_data() -> Self::InitData128     unsafe fn __init_data() -> Self::InitData {
129         AllData(PhantomData)
130     }
131 }
132 
133 /// Stack initializer helper type. Use [`stack_pin_init`] instead of this primitive.
134 ///
135 /// # Invariants
136 ///
137 /// If `self.is_init` is true, then `self.value` is initialized.
138 ///
139 /// [`stack_pin_init`]: crate::stack_pin_init
140 pub struct StackInit<T> {
141     value: MaybeUninit<T>,
142     is_init: bool,
143 }
144 
145 impl<T> Drop for StackInit<T> {
146     #[inline]
drop(&mut self)147     fn drop(&mut self) {
148         if self.is_init {
149             // SAFETY: As we are being dropped, we only call this once. And since `self.is_init` is
150             // true, `self.value` is initialized.
151             unsafe { self.value.assume_init_drop() };
152         }
153     }
154 }
155 
156 impl<T> StackInit<T> {
157     /// Creates a new [`StackInit<T>`] that is uninitialized. Use [`stack_pin_init`] instead of this
158     /// primitive.
159     ///
160     /// [`stack_pin_init`]: crate::stack_pin_init
161     #[inline]
uninit() -> Self162     pub fn uninit() -> Self {
163         Self {
164             value: MaybeUninit::uninit(),
165             is_init: false,
166         }
167     }
168 
169     /// Initializes the contents and returns the result.
170     #[inline]
init<E>(self: Pin<&mut Self>, init: impl PinInit<T, E>) -> Result<Pin<&mut T>, E>171     pub fn init<E>(self: Pin<&mut Self>, init: impl PinInit<T, E>) -> Result<Pin<&mut T>, E> {
172         // SAFETY: We never move out of `this`.
173         let this = unsafe { Pin::into_inner_unchecked(self) };
174         // The value is currently initialized, so it needs to be dropped before we can reuse
175         // the memory (this is a safety guarantee of `Pin`).
176         if this.is_init {
177             this.is_init = false;
178             // SAFETY: `this.is_init` was true and therefore `this.value` is initialized.
179             unsafe { this.value.assume_init_drop() };
180         }
181         // SAFETY: The memory slot is valid and this type ensures that it will stay pinned.
182         unsafe { init.__pinned_init(this.value.as_mut_ptr())? };
183         // INVARIANT: `this.value` is initialized above.
184         this.is_init = true;
185         // SAFETY: The slot is now pinned, since we will never give access to `&mut T`.
186         Ok(unsafe { Pin::new_unchecked(this.value.assume_init_mut()) })
187     }
188 }
189 
190 #[test]
stack_init_reuse()191 fn stack_init_reuse() {
192     use ::std::{borrow::ToOwned, println, string::String};
193     use core::pin::pin;
194 
195     #[derive(Debug)]
196     struct Foo {
197         a: usize,
198         b: String,
199     }
200     let mut slot: Pin<&mut StackInit<Foo>> = pin!(StackInit::uninit());
201     let value: Result<Pin<&mut Foo>, core::convert::Infallible> =
202         slot.as_mut().init(crate::init!(Foo {
203             a: 42,
204             b: "Hello".to_owned(),
205         }));
206     let value = value.unwrap();
207     println!("{value:?}");
208     let value: Result<Pin<&mut Foo>, core::convert::Infallible> =
209         slot.as_mut().init(crate::init!(Foo {
210             a: 24,
211             b: "world!".to_owned(),
212         }));
213     let value = value.unwrap();
214     println!("{value:?}");
215 }
216 
217 /// When a value of this type is dropped, it drops a `T`.
218 ///
219 /// Can be forgotten to prevent the drop.
220 pub struct DropGuard<T: ?Sized> {
221     ptr: *mut T,
222 }
223 
224 impl<T: ?Sized> DropGuard<T> {
225     /// Creates a new [`DropGuard<T>`]. It will [`ptr::drop_in_place`] `ptr` when it gets dropped.
226     ///
227     /// # Safety
228     ///
229     /// `ptr` must be a valid pointer.
230     ///
231     /// It is the callers responsibility that `self` will only get dropped if the pointee of `ptr`:
232     /// - has not been dropped,
233     /// - is not accessible by any other means,
234     /// - will not be dropped by any other means.
235     #[inline]
new(ptr: *mut T) -> Self236     pub unsafe fn new(ptr: *mut T) -> Self {
237         Self { ptr }
238     }
239 }
240 
241 impl<T: ?Sized> Drop for DropGuard<T> {
242     #[inline]
drop(&mut self)243     fn drop(&mut self) {
244         // SAFETY: A `DropGuard` can only be constructed using the unsafe `new` function
245         // ensuring that this operation is safe.
246         unsafe { ptr::drop_in_place(self.ptr) }
247     }
248 }
249 
250 /// Token used by `PinnedDrop` to prevent calling the function without creating this unsafely
251 /// created struct. This is needed, because the `drop` function is safe, but should not be called
252 /// manually.
253 pub struct OnlyCallFromDrop(());
254 
255 impl OnlyCallFromDrop {
256     /// # Safety
257     ///
258     /// This function should only be called from the [`Drop::drop`] function and only be used to
259     /// delegate the destruction to the pinned destructor [`PinnedDrop::drop`] of the same type.
new() -> Self260     pub unsafe fn new() -> Self {
261         Self(())
262     }
263 }
264 
265 /// Initializer that always fails.
266 ///
267 /// Used by [`assert_pinned!`].
268 ///
269 /// [`assert_pinned!`]: crate::assert_pinned
270 pub struct AlwaysFail<T: ?Sized> {
271     _t: PhantomData<T>,
272 }
273 
274 impl<T: ?Sized> AlwaysFail<T> {
275     /// Creates a new initializer that always fails.
new() -> Self276     pub fn new() -> Self {
277         Self { _t: PhantomData }
278     }
279 }
280 
281 impl<T: ?Sized> Default for AlwaysFail<T> {
default() -> Self282     fn default() -> Self {
283         Self::new()
284     }
285 }
286 
287 // SAFETY: `__pinned_init` always fails, which is always okay.
288 unsafe impl<T: ?Sized> PinInit<T, ()> for AlwaysFail<T> {
__pinned_init(self, _slot: *mut T) -> Result<(), ()>289     unsafe fn __pinned_init(self, _slot: *mut T) -> Result<(), ()> {
290         Err(())
291     }
292 }
293