1 // SPDX-License-Identifier: Apache-2.0 OR MIT
3 //! This module contains API-internal items for pin-init.
5 //! These items must not be used outside of
7 //! - `macros/pin_data.rs`
8 //! - `macros/pinned_drop.rs`
12 /// See the [nomicon] for what subtyping is. See also [this table].
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
16 pub(super) type Invariant<T> = PhantomData<fn(*mut T) -> *mut T>;
18 /// This is the module-internal type implementing `PinInit` and `Init`. It is unsafe to create this
19 /// type, since the closure needs to fulfill the same safety requirement as the
20 /// `__pinned_init`/`__init` functions.
21 pub(crate) struct InitClosure<F, T: ?Sized, E>(pub(crate) F, pub(crate) Invariant<(E, T)>);
23 // SAFETY: While constructing the `InitClosure`, the user promised that it upholds the
24 // `__init` invariants.
25 unsafe impl<T: ?Sized, F, E> Init<T, E> for InitClosure<F, T, E>
27 F: FnOnce(*mut T) -> Result<(), E>,
30 unsafe fn __init(self, slot: *mut T) -> Result<(), E> {
35 // SAFETY: While constructing the `InitClosure`, the user promised that it upholds the
36 // `__pinned_init` invariants.
37 unsafe impl<T: ?Sized, F, E> PinInit<T, E> for InitClosure<F, T, E>
39 F: FnOnce(*mut T) -> Result<(), E>,
42 unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> {
47 /// This trait is only implemented via the `#[pin_data]` proc-macro. It is used to facilitate
48 /// the pin projections within the initializers.
52 /// Only the `init` module is allowed to use this trait.
53 pub unsafe trait HasPinData {
54 type PinData: PinData;
56 unsafe fn __pin_data() -> Self::PinData;
59 /// Marker trait for pinning data of structs.
63 /// Only the `init` module is allowed to use this trait.
64 pub unsafe trait PinData: Copy {
65 type Datee: ?Sized + HasPinData;
67 /// Type inference helper function.
68 fn make_closure<F, O, E>(self, f: F) -> F
70 F: FnOnce(*mut Self::Datee) -> Result<O, E>,
76 /// This trait is automatically implemented for every type. It aims to provide the same type
77 /// inference help as `HasPinData`.
81 /// Only the `init` module is allowed to use this trait.
82 pub unsafe trait HasInitData {
83 type InitData: InitData;
85 unsafe fn __init_data() -> Self::InitData;
88 /// Same function as `PinData`, but for arbitrary data.
92 /// Only the `init` module is allowed to use this trait.
93 pub unsafe trait InitData: Copy {
94 type Datee: ?Sized + HasInitData;
96 /// Type inference helper function.
97 fn make_closure<F, O, E>(self, f: F) -> F
99 F: FnOnce(*mut Self::Datee) -> Result<O, E>,
105 pub struct AllData<T: ?Sized>(PhantomData<fn(Box<T>) -> Box<T>>);
107 impl<T: ?Sized> Clone for AllData<T> {
108 fn clone(&self) -> Self {
113 impl<T: ?Sized> Copy for AllData<T> {}
115 unsafe impl<T: ?Sized> InitData for AllData<T> {
119 unsafe impl<T: ?Sized> HasInitData for T {
120 type InitData = AllData<T>;
122 unsafe fn __init_data() -> Self::InitData {
127 /// Stack initializer helper type. Use [`stack_pin_init`] instead of this primitive.
131 /// If `self.is_init` is true, then `self.value` is initialized.
133 /// [`stack_pin_init`]: kernel::stack_pin_init
134 pub struct StackInit<T> {
135 value: MaybeUninit<T>,
139 impl<T> Drop for StackInit<T> {
143 // SAFETY: As we are being dropped, we only call this once. And since `self.is_init` is
144 // true, `self.value` is initialized.
145 unsafe { self.value.assume_init_drop() };
150 impl<T> StackInit<T> {
151 /// Creates a new [`StackInit<T>`] that is uninitialized. Use [`stack_pin_init`] instead of this
154 /// [`stack_pin_init`]: kernel::stack_pin_init
156 pub fn uninit() -> Self {
158 value: MaybeUninit::uninit(),
163 /// Initializes the contents and returns the result.
165 pub fn init<E>(self: Pin<&mut Self>, init: impl PinInit<T, E>) -> Result<Pin<&mut T>, E> {
166 // SAFETY: We never move out of `this`.
167 let this = unsafe { Pin::into_inner_unchecked(self) };
168 // The value is currently initialized, so it needs to be dropped before we can reuse
169 // the memory (this is a safety guarantee of `Pin`).
171 this.is_init = false;
172 // SAFETY: `this.is_init` was true and therefore `this.value` is initialized.
173 unsafe { this.value.assume_init_drop() };
175 // SAFETY: The memory slot is valid and this type ensures that it will stay pinned.
176 unsafe { init.__pinned_init(this.value.as_mut_ptr())? };
177 // INVARIANT: `this.value` is initialized above.
179 // SAFETY: The slot is now pinned, since we will never give access to `&mut T`.
180 Ok(unsafe { Pin::new_unchecked(this.value.assume_init_mut()) })
184 /// When a value of this type is dropped, it drops a `T`.
186 /// Can be forgotten to prevent the drop.
187 pub struct DropGuard<T: ?Sized> {
191 impl<T: ?Sized> DropGuard<T> {
192 /// Creates a new [`DropGuard<T>`]. It will [`ptr::drop_in_place`] `ptr` when it gets dropped.
196 /// `ptr` must be a valid pointer.
198 /// It is the callers responsibility that `self` will only get dropped if the pointee of `ptr`:
199 /// - has not been dropped,
200 /// - is not accessible by any other means,
201 /// - will not be dropped by any other means.
203 pub unsafe fn new(ptr: *mut T) -> Self {
208 impl<T: ?Sized> Drop for DropGuard<T> {
211 // SAFETY: A `DropGuard` can only be constructed using the unsafe `new` function
212 // ensuring that this operation is safe.
213 unsafe { ptr::drop_in_place(self.ptr) }
217 /// Token used by `PinnedDrop` to prevent calling the function without creating this unsafely
218 /// created struct. This is needed, because the `drop` function is safe, but should not be called
220 pub struct OnlyCallFromDrop(());
222 impl OnlyCallFromDrop {
225 /// This function should only be called from the [`Drop::drop`] function and only be used to
226 /// delegate the destruction to the pinned destructor [`PinnedDrop::drop`] of the same type.
227 pub unsafe fn new() -> Self {