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