260 lines · rust
1// SPDX-License-Identifier: Apache-2.0 OR MIT2 3//! This module contains API-internal items for pin-init.4//!5//! These items must not be used outside of6//! - `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.html15/// [this table]: https://doc.rust-lang.org/nomicon/phantom-data.html#table-of-phantomdata-patterns16pub(super) type Invariant<T> = PhantomData<fn(*mut T) -> *mut T>;17 18/// This is the module-internal type implementing `PinInit` and `Init`. It is unsafe to create this19/// type, since the closure needs to fulfill the same safety requirement as the20/// `__pinned_init`/`__init` functions.21pub(crate) struct InitClosure<F, T: ?Sized, E>(pub(crate) F, pub(crate) Invariant<(E, T)>);22 23// SAFETY: While constructing the `InitClosure`, the user promised that it upholds the24// `__init` invariants.25unsafe impl<T: ?Sized, F, E> Init<T, E> for InitClosure<F, T, E>26where27 F: FnOnce(*mut T) -> Result<(), E>,28{29 #[inline]30 unsafe fn __init(self, slot: *mut T) -> Result<(), E> {31 (self.0)(slot)32 }33}34 35// SAFETY: While constructing the `InitClosure`, the user promised that it upholds the36// `__pinned_init` invariants.37unsafe impl<T: ?Sized, F, E> PinInit<T, E> for InitClosure<F, T, E>38where39 F: FnOnce(*mut T) -> Result<(), E>,40{41 #[inline]42 unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> {43 (self.0)(slot)44 }45}46 47/// This trait is only implemented via the `#[pin_data]` proc-macro. It is used to facilitate48/// the pin projections within the initializers.49///50/// # Safety51///52/// Only the `init` module is allowed to use this trait.53pub unsafe trait HasPinData {54 type PinData: PinData;55 56 unsafe fn __pin_data() -> Self::PinData;57}58 59/// Marker trait for pinning data of structs.60///61/// # Safety62///63/// Only the `init` module is allowed to use this trait.64pub unsafe trait PinData: Copy {65 type Datee: ?Sized + HasPinData;66 67 /// Type inference helper function.68 fn make_closure<F, O, E>(self, f: F) -> F69 where70 F: FnOnce(*mut Self::Datee) -> Result<O, E>,71 {72 f73 }74}75 76/// This trait is automatically implemented for every type. It aims to provide the same type77/// inference help as `HasPinData`.78///79/// # Safety80///81/// Only the `init` module is allowed to use this trait.82pub unsafe trait HasInitData {83 type InitData: InitData;84 85 unsafe fn __init_data() -> Self::InitData;86}87 88/// Same function as `PinData`, but for arbitrary data.89///90/// # Safety91///92/// Only the `init` module is allowed to use this trait.93pub unsafe trait InitData: Copy {94 type Datee: ?Sized + HasInitData;95 96 /// Type inference helper function.97 fn make_closure<F, O, E>(self, f: F) -> F98 where99 F: FnOnce(*mut Self::Datee) -> Result<O, E>,100 {101 f102 }103}104 105pub struct AllData<T: ?Sized>(PhantomData<fn(Box<T>) -> Box<T>>);106 107impl<T: ?Sized> Clone for AllData<T> {108 fn clone(&self) -> Self {109 *self110 }111}112 113impl<T: ?Sized> Copy for AllData<T> {}114 115unsafe impl<T: ?Sized> InitData for AllData<T> {116 type Datee = T;117}118 119unsafe impl<T: ?Sized> HasInitData for T {120 type InitData = AllData<T>;121 122 unsafe fn __init_data() -> Self::InitData {123 AllData(PhantomData)124 }125}126 127/// Stack initializer helper type. Use [`stack_pin_init`] instead of this primitive.128///129/// # Invariants130///131/// If `self.is_init` is true, then `self.value` is initialized.132///133/// [`stack_pin_init`]: kernel::stack_pin_init134pub struct StackInit<T> {135 value: MaybeUninit<T>,136 is_init: bool,137}138 139impl<T> Drop for StackInit<T> {140 #[inline]141 fn drop(&mut self) {142 if self.is_init {143 // SAFETY: As we are being dropped, we only call this once. And since `self.is_init` is144 // true, `self.value` is initialized.145 unsafe { self.value.assume_init_drop() };146 }147 }148}149 150impl<T> StackInit<T> {151 /// Creates a new [`StackInit<T>`] that is uninitialized. Use [`stack_pin_init`] instead of this152 /// primitive.153 ///154 /// [`stack_pin_init`]: kernel::stack_pin_init155 #[inline]156 pub fn uninit() -> Self {157 Self {158 value: MaybeUninit::uninit(),159 is_init: false,160 }161 }162 163 /// Initializes the contents and returns the result.164 #[inline]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 reuse169 // the memory (this is a safety guarantee of `Pin`).170 if this.is_init {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() };174 }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.178 this.is_init = true;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()) })181 }182}183 184/// When a value of this type is dropped, it drops a `T`.185///186/// Can be forgotten to prevent the drop.187pub struct DropGuard<T: ?Sized> {188 ptr: *mut T,189}190 191impl<T: ?Sized> DropGuard<T> {192 /// Creates a new [`DropGuard<T>`]. It will [`ptr::drop_in_place`] `ptr` when it gets dropped.193 ///194 /// # Safety195 ///196 /// `ptr` must be a valid pointer.197 ///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.202 #[inline]203 pub unsafe fn new(ptr: *mut T) -> Self {204 Self { ptr }205 }206}207 208impl<T: ?Sized> Drop for DropGuard<T> {209 #[inline]210 fn drop(&mut self) {211 // SAFETY: A `DropGuard` can only be constructed using the unsafe `new` function212 // ensuring that this operation is safe.213 unsafe { ptr::drop_in_place(self.ptr) }214 }215}216 217/// Token used by `PinnedDrop` to prevent calling the function without creating this unsafely218/// created struct. This is needed, because the `drop` function is safe, but should not be called219/// manually.220pub struct OnlyCallFromDrop(());221 222impl OnlyCallFromDrop {223 /// # Safety224 ///225 /// This function should only be called from the [`Drop::drop`] function and only be used to226 /// delegate the destruction to the pinned destructor [`PinnedDrop::drop`] of the same type.227 pub unsafe fn new() -> Self {228 Self(())229 }230}231 232/// Initializer that always fails.233///234/// Used by [`assert_pinned!`].235///236/// [`assert_pinned!`]: crate::assert_pinned237pub struct AlwaysFail<T: ?Sized> {238 _t: PhantomData<T>,239}240 241impl<T: ?Sized> AlwaysFail<T> {242 /// Creates a new initializer that always fails.243 pub fn new() -> Self {244 Self { _t: PhantomData }245 }246}247 248impl<T: ?Sized> Default for AlwaysFail<T> {249 fn default() -> Self {250 Self::new()251 }252}253 254// SAFETY: `__pinned_init` always fails, which is always okay.255unsafe impl<T: ?Sized> PinInit<T, ()> for AlwaysFail<T> {256 unsafe fn __pinned_init(self, _slot: *mut T) -> Result<(), ()> {257 Err(())258 }259}260