pin_init/__internal.rs
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
8use 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
17pub(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.
23pub(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.
27unsafe impl<T: ?Sized, F, E> Init<T, E> for InitClosure<F, T, E>
28where
29 F: FnOnce(*mut T) -> Result<(), E>,
30{
31 #[inline]
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.
39unsafe impl<T: ?Sized, F, E> PinInit<T, E> for InitClosure<F, T, E>
40where
41 F: FnOnce(*mut T) -> Result<(), E>,
42{
43 #[inline]
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.
55pub unsafe trait HasPinData {
56 type PinData: PinData;
57
58 #[expect(clippy::missing_safety_doc)]
59 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.
67pub unsafe trait PinData: Copy {
68 type Datee: ?Sized + HasPinData;
69
70 /// Type inference helper function.
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.
85pub unsafe trait HasInitData {
86 type InitData: InitData;
87
88 #[expect(clippy::missing_safety_doc)]
89 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.
97pub unsafe trait InitData: Copy {
98 type Datee: ?Sized + HasInitData;
99
100 /// Type inference helper function.
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
109pub struct AllData<T: ?Sized>(Invariant<T>);
110
111impl<T: ?Sized> Clone for AllData<T> {
112 fn clone(&self) -> Self {
113 *self
114 }
115}
116
117impl<T: ?Sized> Copy for AllData<T> {}
118
119// SAFETY: TODO.
120unsafe impl<T: ?Sized> InitData for AllData<T> {
121 type Datee = T;
122}
123
124// SAFETY: TODO.
125unsafe impl<T: ?Sized> HasInitData for T {
126 type InitData = AllData<T>;
127
128 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
140pub struct StackInit<T> {
141 value: MaybeUninit<T>,
142 is_init: bool,
143}
144
145impl<T> Drop for StackInit<T> {
146 #[inline]
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
156impl<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]
162 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]
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]
191#[cfg(feature = "std")]
192fn stack_init_reuse() {
193 use ::std::{borrow::ToOwned, println, string::String};
194 use core::pin::pin;
195
196 #[derive(Debug)]
197 struct Foo {
198 a: usize,
199 b: String,
200 }
201 let mut slot: Pin<&mut StackInit<Foo>> = pin!(StackInit::uninit());
202 let value: Result<Pin<&mut Foo>, core::convert::Infallible> =
203 slot.as_mut().init(crate::init!(Foo {
204 a: 42,
205 b: "Hello".to_owned(),
206 }));
207 let value = value.unwrap();
208 println!("{value:?}");
209 let value: Result<Pin<&mut Foo>, core::convert::Infallible> =
210 slot.as_mut().init(crate::init!(Foo {
211 a: 24,
212 b: "world!".to_owned(),
213 }));
214 let value = value.unwrap();
215 println!("{value:?}");
216}
217
218/// When a value of this type is dropped, it drops a `T`.
219///
220/// Can be forgotten to prevent the drop.
221pub struct DropGuard<T: ?Sized> {
222 ptr: *mut T,
223}
224
225impl<T: ?Sized> DropGuard<T> {
226 /// Creates a new [`DropGuard<T>`]. It will [`ptr::drop_in_place`] `ptr` when it gets dropped.
227 ///
228 /// # Safety
229 ///
230 /// `ptr` must be a valid pointer.
231 ///
232 /// It is the callers responsibility that `self` will only get dropped if the pointee of `ptr`:
233 /// - has not been dropped,
234 /// - is not accessible by any other means,
235 /// - will not be dropped by any other means.
236 #[inline]
237 pub unsafe fn new(ptr: *mut T) -> Self {
238 Self { ptr }
239 }
240}
241
242impl<T: ?Sized> Drop for DropGuard<T> {
243 #[inline]
244 fn drop(&mut self) {
245 // SAFETY: A `DropGuard` can only be constructed using the unsafe `new` function
246 // ensuring that this operation is safe.
247 unsafe { ptr::drop_in_place(self.ptr) }
248 }
249}
250
251/// Token used by `PinnedDrop` to prevent calling the function without creating this unsafely
252/// created struct. This is needed, because the `drop` function is safe, but should not be called
253/// manually.
254pub struct OnlyCallFromDrop(());
255
256impl OnlyCallFromDrop {
257 /// # Safety
258 ///
259 /// This function should only be called from the [`Drop::drop`] function and only be used to
260 /// delegate the destruction to the pinned destructor [`PinnedDrop::drop`] of the same type.
261 pub unsafe fn new() -> Self {
262 Self(())
263 }
264}
265
266/// Initializer that always fails.
267///
268/// Used by [`assert_pinned!`].
269///
270/// [`assert_pinned!`]: crate::assert_pinned
271pub struct AlwaysFail<T: ?Sized> {
272 _t: PhantomData<T>,
273}
274
275impl<T: ?Sized> AlwaysFail<T> {
276 /// Creates a new initializer that always fails.
277 pub fn new() -> Self {
278 Self { _t: PhantomData }
279 }
280}
281
282impl<T: ?Sized> Default for AlwaysFail<T> {
283 fn default() -> Self {
284 Self::new()
285 }
286}
287
288// SAFETY: `__pinned_init` always fails, which is always okay.
289unsafe impl<T: ?Sized> PinInit<T, ()> for AlwaysFail<T> {
290 unsafe fn __pinned_init(self, _slot: *mut T) -> Result<(), ()> {
291 Err(())
292 }
293}