bevy_ptr/
lib.rs

1#![doc = include_str!("../README.md")]
2#![no_std]
3#![cfg_attr(docsrs, feature(doc_cfg))]
4#![expect(unsafe_code, reason = "Raw pointers are inherently unsafe.")]
5#![doc(
6    html_logo_url = "https://bevy.org/assets/icon.png",
7    html_favicon_url = "https://bevy.org/assets/icon.png"
8)]
9
10use core::{
11    cell::UnsafeCell,
12    fmt::{self, Debug, Formatter, Pointer},
13    marker::PhantomData,
14    mem::{self, ManuallyDrop, MaybeUninit},
15    num::NonZeroUsize,
16    ops::{Deref, DerefMut},
17    ptr::{self, NonNull},
18};
19
20/// Used as a type argument to [`Ptr`], [`PtrMut`], [`OwningPtr`], and [`MovingPtr`] to specify that the pointer is guaranteed
21/// to be [aligned].
22///
23/// [aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
24#[derive(Debug, Copy, Clone)]
25pub struct Aligned;
26
27/// Used as a type argument to [`Ptr`], [`PtrMut`], [`OwningPtr`], and [`MovingPtr`] to specify that the pointer may not [aligned].
28///
29/// [aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
30#[derive(Debug, Copy, Clone)]
31pub struct Unaligned;
32
33/// Trait that is only implemented for [`Aligned`] and [`Unaligned`] to work around the lack of ability
34/// to have const generics of an enum.
35pub trait IsAligned: sealed::Sealed {
36    /// Reads the value pointed to by `ptr`.
37    ///
38    /// # Safety
39    ///  - `ptr` must be valid for reads.
40    ///  - `ptr` must point to a valid instance of type `T`
41    ///  - If this type is [`Aligned`], then `ptr` must be [properly aligned] for type `T`.
42    ///
43    /// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
44    #[doc(hidden)]
45    unsafe fn read_ptr<T>(ptr: *const T) -> T;
46
47    /// Copies `count * size_of::<T>()` bytes from `src` to `dst`. The source
48    /// and destination must *not* overlap.
49    ///
50    /// # Safety
51    ///  - `src` must be valid for reads of `count * size_of::<T>()` bytes.
52    ///  - `dst` must be valid for writes of `count * size_of::<T>()` bytes.
53    ///  - The region of memory beginning at `src` with a size of `count *
54    ///    size_of::<T>()` bytes must *not* overlap with the region of memory
55    ///    beginning at `dst` with the same size.
56    ///  - If this type is [`Aligned`], then both `src` and `dst` must properly
57    ///    be aligned for values of type `T`.
58    #[doc(hidden)]
59    unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize);
60
61    /// Reads the value pointed to by `ptr`.
62    ///
63    /// # Safety
64    ///  - `ptr` must be valid for reads and writes.
65    ///  - `ptr` must point to a valid instance of type `T`
66    ///  - If this type is [`Aligned`], then `ptr` must be [properly aligned] for type `T`.
67    ///  - The value pointed to by `ptr` must be valid for dropping.
68    ///  - While `drop_in_place` is executing, the only way to access parts of `ptr` is through
69    ///    the `&mut Self` supplied to it's `Drop::drop` impl.
70    ///
71    /// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
72    #[doc(hidden)]
73    unsafe fn drop_in_place<T>(ptr: *mut T);
74}
75
76impl IsAligned for Aligned {
77    #[inline]
78    unsafe fn read_ptr<T>(ptr: *const T) -> T {
79        // SAFETY:
80        //  - The caller is required to ensure that `src` must be valid for reads.
81        //  - The caller is required to ensure that `src` points to a valid instance of type `T`.
82        //  - This type is `Aligned` so the caller must ensure that `src` is properly aligned for type `T`.
83        unsafe { ptr.read() }
84    }
85
86    #[inline]
87    unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize) {
88        // SAFETY:
89        //  - The caller is required to ensure that `src` must be valid for reads.
90        //  - The caller is required to ensure that `dst` must be valid for writes.
91        //  - The caller is required to ensure that `src` and `dst` are aligned.
92        //  - The caller is required to ensure that the memory region covered by `src`
93        //    and `dst`, fitting up to `count` elements do not overlap.
94        unsafe {
95            ptr::copy_nonoverlapping(src, dst, count);
96        }
97    }
98
99    #[inline]
100    unsafe fn drop_in_place<T>(ptr: *mut T) {
101        // SAFETY:
102        //  - The caller is required to ensure that `ptr` must be valid for reads and writes.
103        //  - The caller is required to ensure that `ptr` points to a valid instance of type `T`.
104        //  - This type is `Aligned` so the caller must ensure that `ptr` is properly aligned for type `T`.
105        //  - The caller is required to ensure that `ptr` points must be valid for dropping.
106        //  - The caller is required to ensure that the value `ptr` points must not be used after this function
107        //    call.
108        unsafe {
109            ptr::drop_in_place(ptr);
110        }
111    }
112}
113
114impl IsAligned for Unaligned {
115    #[inline]
116    unsafe fn read_ptr<T>(ptr: *const T) -> T {
117        // SAFETY:
118        //  - The caller is required to ensure that `src` must be valid for reads.
119        //  - The caller is required to ensure that `src` points to a valid instance of type `T`.
120        unsafe { ptr.read_unaligned() }
121    }
122
123    #[inline]
124    unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize) {
125        // SAFETY:
126        //  - The caller is required to ensure that `src` must be valid for reads.
127        //  - The caller is required to ensure that `dst` must be valid for writes.
128        //  - This is doing a byte-wise copy. `src` and `dst` are always guaranteed to be
129        //    aligned.
130        //  - The caller is required to ensure that the memory region covered by `src`
131        //    and `dst`, fitting up to `count` elements do not overlap.
132        unsafe {
133            ptr::copy_nonoverlapping::<u8>(
134                src.cast::<u8>(),
135                dst.cast::<u8>(),
136                count * size_of::<T>(),
137            );
138        }
139    }
140
141    #[inline]
142    unsafe fn drop_in_place<T>(ptr: *mut T) {
143        // SAFETY:
144        //  - The caller is required to ensure that `ptr` must be valid for reads and writes.
145        //  - The caller is required to ensure that `ptr` points to a valid instance of type `T`.
146        //  - This type is not `Aligned` so the caller does not need to ensure that `ptr` is properly aligned for type `T`.
147        //  - The caller is required to ensure that `ptr` points must be valid for dropping.
148        //  - The caller is required to ensure that the value `ptr` points must not be used after this function
149        //    call.
150        unsafe {
151            drop(ptr.read_unaligned());
152        }
153    }
154}
155
156mod sealed {
157    pub trait Sealed {}
158    impl Sealed for super::Aligned {}
159    impl Sealed for super::Unaligned {}
160}
161
162/// A newtype around [`NonNull`] that only allows conversion to read-only borrows or pointers.
163///
164/// This type can be thought of as the `*const T` to [`NonNull<T>`]'s `*mut T`.
165#[repr(transparent)]
166pub struct ConstNonNull<T: ?Sized>(NonNull<T>);
167
168impl<T: ?Sized> ConstNonNull<T> {
169    /// Creates a new `ConstNonNull` if `ptr` is non-null.
170    ///
171    /// # Examples
172    ///
173    /// ```
174    /// use bevy_ptr::ConstNonNull;
175    ///
176    /// let x = 0u32;
177    /// let ptr = ConstNonNull::<u32>::new(&x as *const _).expect("ptr is null!");
178    ///
179    /// if let Some(ptr) = ConstNonNull::<u32>::new(core::ptr::null()) {
180    ///     unreachable!();
181    /// }
182    /// ```
183    pub fn new(ptr: *const T) -> Option<Self> {
184        NonNull::new(ptr.cast_mut()).map(Self)
185    }
186
187    /// Creates a new `ConstNonNull`.
188    ///
189    /// # Safety
190    ///
191    /// `ptr` must be non-null.
192    ///
193    /// # Examples
194    ///
195    /// ```
196    /// use bevy_ptr::ConstNonNull;
197    ///
198    /// let x = 0u32;
199    /// let ptr = unsafe { ConstNonNull::new_unchecked(&x as *const _) };
200    /// ```
201    ///
202    /// *Incorrect* usage of this function:
203    ///
204    /// ```rust,no_run
205    /// use bevy_ptr::ConstNonNull;
206    ///
207    /// // NEVER DO THAT!!! This is undefined behavior. ⚠️
208    /// let ptr = unsafe { ConstNonNull::<u32>::new_unchecked(core::ptr::null()) };
209    /// ```
210    pub const unsafe fn new_unchecked(ptr: *const T) -> Self {
211        // SAFETY: This function's safety invariants are identical to `NonNull::new_unchecked`
212        // The caller must satisfy all of them.
213        unsafe { Self(NonNull::new_unchecked(ptr.cast_mut())) }
214    }
215
216    /// Returns a shared reference to the value.
217    ///
218    /// # Safety
219    ///
220    /// When calling this method, you have to ensure that all of the following is true:
221    ///
222    /// * The pointer must be [properly aligned].
223    ///
224    /// * It must be "dereferenceable" in the sense defined in [the module documentation].
225    ///
226    /// * The pointer must point to an initialized instance of `T`.
227    ///
228    /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
229    ///   arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
230    ///   In particular, while this reference exists, the memory the pointer points to must
231    ///   not get mutated (except inside `UnsafeCell`).
232    ///
233    /// This applies even if the result of this method is unused!
234    /// (The part about being initialized is not yet fully decided, but until
235    /// it is, the only safe approach is to ensure that they are indeed initialized.)
236    ///
237    /// # Examples
238    ///
239    /// ```
240    /// use bevy_ptr::ConstNonNull;
241    ///
242    /// let mut x = 0u32;
243    /// let ptr = ConstNonNull::new(&mut x as *mut _).expect("ptr is null!");
244    ///
245    /// let ref_x = unsafe { ptr.as_ref() };
246    /// println!("{ref_x}");
247    /// ```
248    ///
249    /// [the module documentation]: core::ptr#safety
250    /// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
251    #[inline]
252    pub unsafe fn as_ref<'a>(&self) -> &'a T {
253        // SAFETY: This function's safety invariants are identical to `NonNull::as_ref`
254        // The caller must satisfy all of them.
255        unsafe { self.0.as_ref() }
256    }
257}
258
259impl<T: ?Sized> From<NonNull<T>> for ConstNonNull<T> {
260    fn from(value: NonNull<T>) -> ConstNonNull<T> {
261        ConstNonNull(value)
262    }
263}
264
265impl<'a, T: ?Sized> From<&'a T> for ConstNonNull<T> {
266    fn from(value: &'a T) -> ConstNonNull<T> {
267        ConstNonNull(NonNull::from(value))
268    }
269}
270
271impl<'a, T: ?Sized> From<&'a mut T> for ConstNonNull<T> {
272    fn from(value: &'a mut T) -> ConstNonNull<T> {
273        ConstNonNull(NonNull::from(value))
274    }
275}
276
277/// Type-erased borrow of some unknown type chosen when constructing this type.
278///
279/// This type tries to act "borrow-like" which means that:
280/// - It should be considered immutable: its target must not be changed while this pointer is alive.
281/// - It must always point to a valid value of whatever the pointee type is.
282/// - The lifetime `'a` accurately represents how long the pointer is valid for.
283/// - If `A` is [`Aligned`], the pointer must always be [properly aligned] for the unknown pointee type.
284///
285/// It may be helpful to think of this type as similar to `&'a dyn Any` but without
286/// the metadata and able to point to data that does not correspond to a Rust type.
287///
288/// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
289#[derive(Copy, Clone)]
290#[repr(transparent)]
291pub struct Ptr<'a, A: IsAligned = Aligned>(NonNull<u8>, PhantomData<(&'a u8, A)>);
292
293/// Type-erased mutable borrow of some unknown type chosen when constructing this type.
294///
295/// This type tries to act "borrow-like" which means that:
296/// - Pointer is considered exclusive and mutable. It cannot be cloned as this would lead to
297///   aliased mutability.
298/// - It must always point to a valid value of whatever the pointee type is.
299/// - The lifetime `'a` accurately represents how long the pointer is valid for.
300/// - If `A` is [`Aligned`], the pointer must always be [properly aligned] for the unknown pointee type.
301///
302/// It may be helpful to think of this type as similar to `&'a mut dyn Any` but without
303/// the metadata and able to point to data that does not correspond to a Rust type.
304///
305/// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
306#[repr(transparent)]
307pub struct PtrMut<'a, A: IsAligned = Aligned>(NonNull<u8>, PhantomData<(&'a mut u8, A)>);
308
309/// Type-erased [`Box`]-like pointer to some unknown type chosen when constructing this type.
310///
311/// Conceptually represents ownership of whatever data is being pointed to and so is
312/// responsible for calling its `Drop` impl. This pointer is _not_ responsible for freeing
313/// the memory pointed to by this pointer as it may be pointing to an element in a `Vec` or
314/// to a local in a function etc.
315///
316/// This type tries to act "borrow-like" which means that:
317/// - Pointer should be considered exclusive and mutable. It cannot be cloned as this would lead
318///   to aliased mutability and potentially use after free bugs.
319/// - It must always point to a valid value of whatever the pointee type is.
320/// - The lifetime `'a` accurately represents how long the pointer is valid for.
321/// - If `A` is [`Aligned`], the pointer must always be [properly aligned] for the unknown pointee type.
322///
323/// It may be helpful to think of this type as similar to `&'a mut ManuallyDrop<dyn Any>` but
324/// without the metadata and able to point to data that does not correspond to a Rust type.
325///
326/// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
327/// [`Box`]: https://doc.rust-lang.org/std/boxed/struct.Box.html
328#[repr(transparent)]
329pub struct OwningPtr<'a, A: IsAligned = Aligned>(NonNull<u8>, PhantomData<(&'a mut u8, A)>);
330
331/// A [`Box`]-like pointer for moving a value to a new memory location without needing to pass by
332/// value.
333///
334/// Conceptually represents ownership of whatever data is being pointed to and will call its
335/// [`Drop`] impl upon being dropped. This pointer is _not_ responsible for freeing
336/// the memory pointed to by this pointer as it may be pointing to an element in a `Vec` or
337/// to a local in a function etc.
338///
339/// This type tries to act "borrow-like" which means that:
340/// - Pointer should be considered exclusive and mutable. It cannot be cloned as this would lead
341///   to aliased mutability and potentially use after free bugs.
342/// - It must always point to a valid value of whatever the pointee type is.
343/// - The lifetime `'a` accurately represents how long the pointer is valid for.
344/// - It does not support pointer arithmetic in any way.
345/// - If `A` is [`Aligned`], the pointer must always be [properly aligned] for the type `T`.
346///
347/// A value can be deconstructed into its fields via [`deconstruct_moving_ptr`], see it's documentation
348/// for an example on how to use it.
349///
350/// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
351/// [`Box`]: https://doc.rust-lang.org/std/boxed/struct.Box.html
352#[repr(transparent)]
353pub struct MovingPtr<'a, T, A: IsAligned = Aligned>(NonNull<T>, PhantomData<(&'a mut T, A)>);
354
355macro_rules! impl_ptr {
356    ($ptr:ident) => {
357        impl<'a> $ptr<'a, Aligned> {
358            /// Removes the alignment requirement of this pointer
359            pub fn to_unaligned(self) -> $ptr<'a, Unaligned> {
360                $ptr(self.0, PhantomData)
361            }
362        }
363
364        impl<'a, A: IsAligned> From<$ptr<'a, A>> for NonNull<u8> {
365            fn from(ptr: $ptr<'a, A>) -> Self {
366                ptr.0
367            }
368        }
369
370        impl<A: IsAligned> $ptr<'_, A> {
371            /// Calculates the offset from a pointer.
372            /// As the pointer is type-erased, there is no size information available. The provided
373            /// `count` parameter is in raw bytes.
374            ///
375            /// *See also: [`ptr::offset`][ptr_offset]*
376            ///
377            /// # Safety
378            /// - The offset cannot make the existing ptr null, or take it out of bounds for its allocation.
379            /// - If the `A` type parameter is [`Aligned`] then the offset must not make the resulting pointer
380            ///   be unaligned for the pointee type.
381            /// - The value pointed by the resulting pointer must outlive the lifetime of this pointer.
382            ///
383            /// [ptr_offset]: https://doc.rust-lang.org/std/primitive.pointer.html#method.offset
384            #[inline]
385            pub unsafe fn byte_offset(self, count: isize) -> Self {
386                Self(
387                    // SAFETY: The caller upholds safety for `offset` and ensures the result is not null.
388                    unsafe { NonNull::new_unchecked(self.as_ptr().offset(count)) },
389                    PhantomData,
390                )
391            }
392
393            /// Calculates the offset from a pointer (convenience for `.offset(count as isize)`).
394            /// As the pointer is type-erased, there is no size information available. The provided
395            /// `count` parameter is in raw bytes.
396            ///
397            /// *See also: [`ptr::add`][ptr_add]*
398            ///
399            /// # Safety
400            /// - The offset cannot make the existing ptr null, or take it out of bounds for its allocation.
401            /// - If the `A` type parameter is [`Aligned`] then the offset must not make the resulting pointer
402            ///   be unaligned for the pointee type.
403            /// - The value pointed by the resulting pointer must outlive the lifetime of this pointer.
404            ///
405            /// [ptr_add]: https://doc.rust-lang.org/std/primitive.pointer.html#method.add
406            #[inline]
407            pub unsafe fn byte_add(self, count: usize) -> Self {
408                Self(
409                    // SAFETY: The caller upholds safety for `add` and ensures the result is not null.
410                    unsafe { NonNull::new_unchecked(self.as_ptr().add(count)) },
411                    PhantomData,
412                )
413            }
414        }
415
416        impl<A: IsAligned> Pointer for $ptr<'_, A> {
417            #[inline]
418            fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
419                Pointer::fmt(&self.0, f)
420            }
421        }
422
423        impl Debug for $ptr<'_, Aligned> {
424            #[inline]
425            fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
426                write!(f, "{}<Aligned>({:?})", stringify!($ptr), self.0)
427            }
428        }
429
430        impl Debug for $ptr<'_, Unaligned> {
431            #[inline]
432            fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
433                write!(f, "{}<Unaligned>({:?})", stringify!($ptr), self.0)
434            }
435        }
436    };
437}
438
439impl_ptr!(Ptr);
440impl_ptr!(PtrMut);
441impl_ptr!(OwningPtr);
442
443impl<'a, T> MovingPtr<'a, T, Aligned> {
444    /// Removes the alignment requirement of this pointer
445    #[inline]
446    pub fn to_unaligned(self) -> MovingPtr<'a, T, Unaligned> {
447        let value = MovingPtr(self.0, PhantomData);
448        mem::forget(self);
449        value
450    }
451
452    /// Creates a [`MovingPtr`] from a provided value of type `T`.
453    ///
454    /// For a safer alternative, it is strongly advised to use [`move_as_ptr`] where possible.
455    ///
456    /// # Safety
457    /// - `value` must store a properly initialized value of type `T`.
458    /// - Once the returned [`MovingPtr`] has been used, `value` must be treated as
459    ///   it were uninitialized unless it was explicitly leaked via [`core::mem::forget`].
460    #[inline]
461    pub unsafe fn from_value(value: &'a mut MaybeUninit<T>) -> Self {
462        // SAFETY:
463        // - MaybeUninit<T> has the same memory layout as T
464        // - The caller guarantees that `value` must point to a valid instance of type `T`.
465        MovingPtr(NonNull::from(value).cast::<T>(), PhantomData)
466    }
467}
468
469impl<'a, T, A: IsAligned> MovingPtr<'a, T, A> {
470    /// Creates a new instance from a raw pointer.
471    ///
472    /// For a safer alternative, it is strongly advised to use [`move_as_ptr`] where possible.
473    ///
474    /// # Safety
475    /// - `inner` must point to valid value of `T`.
476    /// - If the `A` type parameter is [`Aligned`] then `inner` must be be [properly aligned] for `T`.
477    /// - `inner` must have correct provenance to allow read and writes of the pointee type.
478    /// - The lifetime `'a` must be constrained such that this [`MovingPtr`] will stay valid and nothing
479    ///   else can read or mutate the pointee while this [`MovingPtr`] is live.
480    ///
481    /// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
482    #[inline]
483    pub unsafe fn new(inner: NonNull<T>) -> Self {
484        Self(inner, PhantomData)
485    }
486
487    /// Partially moves out some fields inside of `self`.
488    ///
489    /// The partially returned value is returned back pointing to [`MaybeUninit<T>`].
490    ///
491    /// While calling this function is safe, care must be taken with the returned `MovingPtr` as it
492    /// points to a value that may no longer be completely valid.
493    ///
494    /// # Example
495    ///
496    /// ```
497    /// use core::mem::{offset_of, MaybeUninit, forget};
498    /// use bevy_ptr::{MovingPtr, move_as_ptr};
499    /// # struct FieldAType(usize);
500    /// # struct FieldBType(usize);
501    /// # struct FieldCType(usize);
502    /// # fn insert<T>(_ptr: MovingPtr<'_, T>) {}
503    ///
504    /// struct Parent {
505    ///   field_a: FieldAType,
506    ///   field_b: FieldBType,
507    ///   field_c: FieldCType,
508    /// }
509    ///
510    /// # let parent = Parent {
511    /// #   field_a: FieldAType(0),
512    /// #   field_b: FieldBType(0),
513    /// #   field_c: FieldCType(0),
514    /// # };
515    ///
516    /// // Converts `parent` into a `MovingPtr`
517    /// move_as_ptr!(parent);
518    ///
519    /// // SAFETY:
520    /// // - `field_a` and `field_b` are both unique.
521    /// let (partial_parent, ()) = MovingPtr::partial_move(parent, |parent_ptr| unsafe {
522    ///   bevy_ptr::deconstruct_moving_ptr!({
523    ///     let Parent { field_a, field_b, field_c } = parent_ptr;
524    ///   });
525    ///   
526    ///   insert(field_a);
527    ///   insert(field_b);
528    ///   forget(field_c);
529    /// });
530    ///
531    /// // Move the rest of fields out of the parent.
532    /// // SAFETY:
533    /// // - `field_c` is by itself unique and does not conflict with the previous accesses
534    /// //   inside `partial_move`.
535    /// unsafe {
536    ///   bevy_ptr::deconstruct_moving_ptr!({
537    ///     let MaybeUninit::<Parent> { field_a: _, field_b: _, field_c } = partial_parent;
538    ///   });
539    ///
540    ///   insert(field_c);
541    /// }
542    /// ```
543    ///
544    /// [`forget`]: core::mem::forget
545    #[inline]
546    pub fn partial_move<R>(
547        self,
548        f: impl FnOnce(MovingPtr<'_, T, A>) -> R,
549    ) -> (MovingPtr<'a, MaybeUninit<T>, A>, R) {
550        let partial_ptr = self.0;
551        let ret = f(self);
552        (
553            MovingPtr(partial_ptr.cast::<MaybeUninit<T>>(), PhantomData),
554            ret,
555        )
556    }
557
558    /// Reads the value pointed to by this pointer.
559    #[inline]
560    pub fn read(self) -> T {
561        // SAFETY:
562        //  - `self.0` must be valid for reads as this type owns the value it points to.
563        //  - `self.0` must always point to a valid instance of type `T`
564        //  - If `A` is [`Aligned`], then `ptr` must be properly aligned for type `T`.
565        let value = unsafe { A::read_ptr(self.0.as_ptr()) };
566        mem::forget(self);
567        value
568    }
569
570    /// Writes the value pointed to by this pointer to a provided location.
571    ///
572    /// This does *not* drop the value stored at `dst` and it's the caller's responsibility
573    /// to ensure that it's properly dropped.
574    ///
575    /// # Safety
576    ///  - `dst` must be valid for writes.
577    ///  - If the `A` type parameter is [`Aligned`] then `dst` must be [properly aligned] for `T`.
578    ///
579    /// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
580    #[inline]
581    pub unsafe fn write_to(self, dst: *mut T) {
582        let src = self.0.as_ptr();
583        mem::forget(self);
584        // SAFETY:
585        //  - `src` must be valid for reads as this pointer is considered to own the value it points to.
586        //  - The caller is required to ensure that `dst` must be valid for writes.
587        //  - As `A` is `Aligned`, the caller is required to ensure that `dst` is aligned and `src` must
588        //    be aligned by the type's invariants.
589        unsafe { A::copy_nonoverlapping(src, dst, 1) };
590    }
591
592    /// Writes the value pointed to by this pointer into `dst`.
593    ///
594    /// The value previously stored at `dst` will be dropped.
595    #[inline]
596    pub fn assign_to(self, dst: &mut T) {
597        // SAFETY:
598        // - `dst` is a mutable borrow, it must point to a valid instance of `T`.
599        // - `dst` is a mutable borrow, it must point to value that is valid for dropping.
600        // - `dst` is a mutable borrow, it must not alias any other access.
601        unsafe {
602            ptr::drop_in_place(dst);
603        }
604        // SAFETY:
605        // - `dst` is a mutable borrow, it must be valid for writes.
606        // - `dst` is a mutable borrow, it must always be aligned.
607        unsafe {
608            self.write_to(dst);
609        }
610    }
611
612    /// Creates a [`MovingPtr`] for a specific field within `self`.
613    ///
614    /// This function is explicitly made for deconstructive moves.
615    ///
616    /// The correct `byte_offset` for a field can be obtained via [`core::mem::offset_of`].
617    ///
618    /// # Safety
619    ///  - `f` must return a non-null pointer to a valid field inside `T`
620    ///  - If `A` is [`Aligned`], then `T` must not be `repr(packed)`
621    ///  - `self` should not be accessed or dropped as if it were a complete value after this function returns.
622    ///    Other fields that have not been moved out of may still be accessed or dropped separately.
623    ///  - This function cannot alias the field with any other access, including other calls to [`move_field`]
624    ///    for the same field, without first calling [`forget`] on it first.
625    ///
626    /// A result of the above invariants means that any operation that could cause `self` to be dropped while
627    /// the pointers to the fields are held will result in undefined behavior. This requires exctra caution
628    /// around code that may panic. See the example below for an example of how to safely use this function.
629    ///
630    /// # Example
631    ///
632    /// ```
633    /// use core::mem::offset_of;
634    /// use bevy_ptr::{MovingPtr, move_as_ptr};
635    /// # struct FieldAType(usize);
636    /// # struct FieldBType(usize);
637    /// # struct FieldCType(usize);
638    /// # fn insert<T>(_ptr: MovingPtr<'_, T>) {}
639    ///
640    /// struct Parent {
641    ///   field_a: FieldAType,
642    ///   field_b: FieldBType,
643    ///   field_c: FieldCType,
644    /// }
645    ///
646    /// let parent = Parent {
647    ///    field_a: FieldAType(0),
648    ///    field_b: FieldBType(0),
649    ///    field_c: FieldCType(0),
650    /// };
651    ///
652    /// // Converts `parent` into a `MovingPtr`.
653    /// move_as_ptr!(parent);
654    ///
655    /// unsafe {
656    ///    let field_a = parent.move_field(|ptr| &raw mut (*ptr).field_a);
657    ///    let field_b = parent.move_field(|ptr| &raw mut (*ptr).field_b);
658    ///    let field_c = parent.move_field(|ptr| &raw mut (*ptr).field_c);
659    ///    // Each call to insert may panic! Ensure that `parent_ptr` cannot be dropped before
660    ///    // calling them!
661    ///    core::mem::forget(parent);
662    ///    insert(field_a);
663    ///    insert(field_b);
664    ///    insert(field_c);
665    /// }
666    /// ```
667    ///
668    /// [`forget`]: core::mem::forget
669    /// [`move_field`]: Self::move_field
670    #[inline(always)]
671    pub unsafe fn move_field<U>(&self, f: impl Fn(*mut T) -> *mut U) -> MovingPtr<'a, U, A> {
672        MovingPtr(
673            // SAFETY: The caller must ensure that `U` is the correct type for the field at `byte_offset`.
674            unsafe { NonNull::new_unchecked(f(self.0.as_ptr())) },
675            PhantomData,
676        )
677    }
678}
679
680impl<'a, T, A: IsAligned> MovingPtr<'a, MaybeUninit<T>, A> {
681    /// Creates a [`MovingPtr`] for a specific field within `self`.
682    ///
683    /// This function is explicitly made for deconstructive moves.
684    ///
685    /// The correct `byte_offset` for a field can be obtained via [`core::mem::offset_of`].
686    ///
687    /// # Safety
688    ///  - `f` must return a non-null pointer to a valid field inside `T`
689    ///  - If `A` is [`Aligned`], then `T` must not be `repr(packed)`
690    ///  - `self` should not be accessed or dropped as if it were a complete value after this function returns.
691    ///    Other fields that have not been moved out of may still be accessed or dropped separately.
692    ///  - This function cannot alias the field with any other access, including other calls to [`move_field`]
693    ///    for the same field, without first calling [`forget`] on it first.
694    ///
695    /// [`forget`]: core::mem::forget
696    /// [`move_field`]: Self::move_field
697    #[inline(always)]
698    pub unsafe fn move_maybe_uninit_field<U>(
699        &self,
700        f: impl Fn(*mut T) -> *mut U,
701    ) -> MovingPtr<'a, MaybeUninit<U>, A> {
702        let self_ptr = self.0.as_ptr().cast::<T>();
703        // SAFETY:
704        // - The caller must ensure that `U` is the correct type for the field at `byte_offset` and thus
705        //   cannot be null.
706        // - `MaybeUninit<T>` is `repr(transparent)` and thus must have the same memory layout as `T``
707        let field_ptr = unsafe { NonNull::new_unchecked(f(self_ptr)) };
708        MovingPtr(field_ptr.cast::<MaybeUninit<U>>(), PhantomData)
709    }
710}
711
712impl<'a, T, A: IsAligned> MovingPtr<'a, MaybeUninit<T>, A> {
713    /// Creates a [`MovingPtr`] pointing to a valid instance of `T`.
714    ///
715    /// See also: [`MaybeUninit::assume_init`].
716    ///
717    /// # Safety
718    /// It's up to the caller to ensure that the value pointed to by `self`
719    /// is really in an initialized state. Calling this when the content is not yet
720    /// fully initialized causes immediate undefined behavior.
721    #[inline]
722    pub unsafe fn assume_init(self) -> MovingPtr<'a, T, A> {
723        let value = MovingPtr(self.0.cast::<T>(), PhantomData);
724        mem::forget(self);
725        value
726    }
727}
728
729impl<T, A: IsAligned> Pointer for MovingPtr<'_, T, A> {
730    #[inline]
731    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
732        Pointer::fmt(&self.0, f)
733    }
734}
735
736impl<T> Debug for MovingPtr<'_, T, Aligned> {
737    #[inline]
738    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
739        write!(f, "MovingPtr<Aligned>({:?})", self.0)
740    }
741}
742
743impl<T> Debug for MovingPtr<'_, T, Unaligned> {
744    #[inline]
745    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
746        write!(f, "MovingPtr<Unaligned>({:?})", self.0)
747    }
748}
749
750impl<'a, T, A: IsAligned> From<MovingPtr<'a, T, A>> for OwningPtr<'a, A> {
751    #[inline]
752    fn from(value: MovingPtr<'a, T, A>) -> Self {
753        // SAFETY:
754        // - `value.0` must always point to valid value of type `T`.
755        // - The type parameter `A` is mirrored from input to output, keeping the same alignment guarantees.
756        // - `value.0` by construction must have correct provenance to allow read and writes of type `T`.
757        // - The lifetime `'a` is mirrored from input to output, keeping the same lifetime guarantees.
758        // - `OwningPtr` maintains the same aliasing invariants as `MovingPtr`.
759        let ptr = unsafe { OwningPtr::new(value.0.cast::<u8>()) };
760        mem::forget(value);
761        ptr
762    }
763}
764
765impl<'a, T> TryFrom<MovingPtr<'a, T, Unaligned>> for MovingPtr<'a, T, Aligned> {
766    type Error = MovingPtr<'a, T, Unaligned>;
767    #[inline]
768    fn try_from(value: MovingPtr<'a, T, Unaligned>) -> Result<Self, Self::Error> {
769        let ptr = value.0;
770        if ptr.as_ptr().is_aligned() {
771            mem::forget(value);
772            Ok(MovingPtr(ptr, PhantomData))
773        } else {
774            Err(value)
775        }
776    }
777}
778
779impl<T> Deref for MovingPtr<'_, T, Aligned> {
780    type Target = T;
781    #[inline]
782    fn deref(&self) -> &Self::Target {
783        let ptr = self.0.as_ptr().debug_ensure_aligned();
784        // SAFETY: This type owns the value it points to and the generic type parameter is `A` so this pointer must be aligned.
785        unsafe { &*ptr }
786    }
787}
788
789impl<T> DerefMut for MovingPtr<'_, T, Aligned> {
790    #[inline]
791    fn deref_mut(&mut self) -> &mut Self::Target {
792        let ptr = self.0.as_ptr().debug_ensure_aligned();
793        // SAFETY: This type owns the value it points to and the generic type parameter is `A` so this pointer must be aligned.
794        unsafe { &mut *ptr }
795    }
796}
797
798impl<T, A: IsAligned> Drop for MovingPtr<'_, T, A> {
799    fn drop(&mut self) {
800        // SAFETY:
801        //  - `self.0` must be valid for reads and writes as this pointer type owns the value it points to.
802        //  - `self.0` must always point to a valid instance of type `T`
803        //  - If `A` is `Aligned`, then `ptr` must be properly aligned for type `T` by construction.
804        //  - `self.0` owns the value it points to so it must always be valid for dropping until this pointer is dropped.
805        //  - This type owns the value it points to, so it's required to not mutably alias value that it points to.
806        unsafe { A::drop_in_place(self.0.as_ptr()) };
807    }
808}
809
810impl<'a, A: IsAligned> Ptr<'a, A> {
811    /// Creates a new instance from a raw pointer.
812    ///
813    /// # Safety
814    /// - `inner` must point to valid value of whatever the pointee type is.
815    /// - If the `A` type parameter is [`Aligned`] then `inner` must be be [properly aligned]for the pointee type.
816    /// - `inner` must have correct provenance to allow reads of the pointee type.
817    /// - The lifetime `'a` must be constrained such that this [`Ptr`] will stay valid and nothing
818    ///   can mutate the pointee while this [`Ptr`] is live except through an [`UnsafeCell`].
819    ///
820    /// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
821    #[inline]
822    pub unsafe fn new(inner: NonNull<u8>) -> Self {
823        Self(inner, PhantomData)
824    }
825
826    /// Transforms this [`Ptr`] into an [`PtrMut`]
827    ///
828    /// # Safety
829    /// * The data pointed to by this `Ptr` must be valid for writes.
830    /// * There must be no active references (mutable or otherwise) to the data underlying this `Ptr`.
831    /// * Another [`PtrMut`] for the same [`Ptr`] must not be created until the first is dropped.
832    #[inline]
833    pub unsafe fn assert_unique(self) -> PtrMut<'a, A> {
834        PtrMut(self.0, PhantomData)
835    }
836
837    /// Transforms this [`Ptr<T>`] into a `&T` with the same lifetime
838    ///
839    /// # Safety
840    /// - `T` must be the erased pointee type for this [`Ptr`].
841    /// - If the type parameter `A` is [`Unaligned`] then this pointer must be be [properly aligned]
842    ///   for the pointee type `T`.
843    ///
844    /// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
845    #[inline]
846    pub unsafe fn deref<T>(self) -> &'a T {
847        let ptr = self.as_ptr().cast::<T>().debug_ensure_aligned();
848        // SAFETY: The caller ensures the pointee is of type `T` and the pointer can be dereferenced.
849        unsafe { &*ptr }
850    }
851
852    /// Gets the underlying pointer, erasing the associated lifetime.
853    ///
854    /// If possible, it is strongly encouraged to use [`deref`](Self::deref) over this function,
855    /// as it retains the lifetime.
856    #[inline]
857    pub fn as_ptr(self) -> *mut u8 {
858        self.0.as_ptr()
859    }
860}
861
862impl<'a, T: ?Sized> From<&'a T> for Ptr<'a> {
863    #[inline]
864    fn from(val: &'a T) -> Self {
865        // SAFETY: The returned pointer has the same lifetime as the passed reference.
866        // Access is immutable.
867        unsafe { Self::new(NonNull::from(val).cast()) }
868    }
869}
870
871impl<'a, A: IsAligned> PtrMut<'a, A> {
872    /// Creates a new instance from a raw pointer.
873    ///
874    /// # Safety
875    /// - `inner` must point to valid value of whatever the pointee type is.
876    /// - If the `A` type parameter is [`Aligned`] then `inner` must be be [properly aligned] for the pointee type.
877    /// - `inner` must have correct provenance to allow read and writes of the pointee type.
878    /// - The lifetime `'a` must be constrained such that this [`PtrMut`] will stay valid and nothing
879    ///   else can read or mutate the pointee while this [`PtrMut`] is live.
880    ///
881    /// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
882    #[inline]
883    pub unsafe fn new(inner: NonNull<u8>) -> Self {
884        Self(inner, PhantomData)
885    }
886
887    /// Transforms this [`PtrMut`] into an [`OwningPtr`]
888    ///
889    /// # Safety
890    /// Must have right to drop or move out of [`PtrMut`].
891    #[inline]
892    pub unsafe fn promote(self) -> OwningPtr<'a, A> {
893        OwningPtr(self.0, PhantomData)
894    }
895
896    /// Transforms this [`PtrMut<T>`] into a `&mut T` with the same lifetime
897    ///
898    /// # Safety
899    /// - `T` must be the erased pointee type for this [`PtrMut`].
900    /// - If the type parameter `A` is [`Unaligned`] then this pointer must be be [properly aligned]
901    ///   for the pointee type `T`.
902    ///
903    /// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
904    #[inline]
905    pub unsafe fn deref_mut<T>(self) -> &'a mut T {
906        let ptr = self.as_ptr().cast::<T>().debug_ensure_aligned();
907        // SAFETY: The caller ensures the pointee is of type `T` and the pointer can be dereferenced.
908        unsafe { &mut *ptr }
909    }
910
911    /// Gets the underlying pointer, erasing the associated lifetime.
912    ///
913    /// If possible, it is strongly encouraged to use [`deref_mut`](Self::deref_mut) over
914    /// this function, as it retains the lifetime.
915    #[inline]
916    pub fn as_ptr(&self) -> *mut u8 {
917        self.0.as_ptr()
918    }
919
920    /// Gets a [`PtrMut`] from this with a smaller lifetime.
921    #[inline]
922    pub fn reborrow(&mut self) -> PtrMut<'_, A> {
923        // SAFETY: the ptrmut we're borrowing from is assumed to be valid
924        unsafe { PtrMut::new(self.0) }
925    }
926
927    /// Gets an immutable reference from this mutable reference
928    #[inline]
929    pub fn as_ref(&self) -> Ptr<'_, A> {
930        // SAFETY: The `PtrMut` type's guarantees about the validity of this pointer are a superset of `Ptr` s guarantees
931        unsafe { Ptr::new(self.0) }
932    }
933}
934
935impl<'a, T: ?Sized> From<&'a mut T> for PtrMut<'a> {
936    #[inline]
937    fn from(val: &'a mut T) -> Self {
938        // SAFETY: The returned pointer has the same lifetime as the passed reference.
939        // The reference is mutable, and thus will not alias.
940        unsafe { Self::new(NonNull::from(val).cast()) }
941    }
942}
943
944impl<'a> OwningPtr<'a> {
945    /// This exists mostly to reduce compile times;
946    /// code is only duplicated per type, rather than per function called.
947    ///
948    /// # Safety
949    ///
950    /// Safety constraints of [`PtrMut::promote`] must be upheld.
951    unsafe fn make_internal<T>(temp: &mut ManuallyDrop<T>) -> OwningPtr<'_> {
952        // SAFETY: The constraints of `promote` are upheld by caller.
953        unsafe { PtrMut::from(&mut *temp).promote() }
954    }
955
956    /// Consumes a value and creates an [`OwningPtr`] to it while ensuring a double drop does not happen.
957    #[inline]
958    pub fn make<T, F: FnOnce(OwningPtr<'_>) -> R, R>(val: T, f: F) -> R {
959        let mut val = ManuallyDrop::new(val);
960        // SAFETY: The value behind the pointer will not get dropped or observed later,
961        // so it's safe to promote it to an owning pointer.
962        f(unsafe { Self::make_internal(&mut val) })
963    }
964}
965
966impl<'a, A: IsAligned> OwningPtr<'a, A> {
967    /// Creates a new instance from a raw pointer.
968    ///
969    /// # Safety
970    /// - `inner` must point to valid value of whatever the pointee type is.
971    /// - If the `A` type parameter is [`Aligned`] then `inner` must be [properly aligned] for the pointee type.
972    /// - `inner` must have correct provenance to allow read and writes of the pointee type.
973    /// - The lifetime `'a` must be constrained such that this [`OwningPtr`] will stay valid and nothing
974    ///   else can read or mutate the pointee while this [`OwningPtr`] is live.
975    ///
976    /// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
977    #[inline]
978    pub unsafe fn new(inner: NonNull<u8>) -> Self {
979        Self(inner, PhantomData)
980    }
981
982    /// Consumes the [`OwningPtr`] to obtain ownership of the underlying data of type `T`.
983    ///
984    /// # Safety
985    /// - `T` must be the erased pointee type for this [`OwningPtr`].
986    /// - If the type parameter `A` is [`Unaligned`] then this pointer must be be [properly aligned]
987    ///   for the pointee type `T`.
988    ///
989    /// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
990    #[inline]
991    pub unsafe fn read<T>(self) -> T {
992        let ptr = self.as_ptr().cast::<T>().debug_ensure_aligned();
993        // SAFETY: The caller ensure the pointee is of type `T` and uphold safety for `read`.
994        unsafe { ptr.read() }
995    }
996
997    /// Casts to a concrete type as a [`MovingPtr`].
998    ///
999    /// # Safety
1000    /// - `T` must be the erased pointee type for this [`OwningPtr`].
1001    #[inline]
1002    pub unsafe fn cast<T>(self) -> MovingPtr<'a, T, A> {
1003        MovingPtr(self.0.cast::<T>(), PhantomData)
1004    }
1005
1006    /// Consumes the [`OwningPtr`] to drop the underlying data of type `T`.
1007    ///
1008    /// # Safety
1009    /// - `T` must be the erased pointee type for this [`OwningPtr`].
1010    /// - If the type parameter `A` is [`Unaligned`] then this pointer must be be [properly aligned]
1011    ///   for the pointee type `T`.
1012    ///
1013    /// [properly aligned]: https://doc.rust-lang.org/std/ptr/index.html#alignment
1014    #[inline]
1015    pub unsafe fn drop_as<T>(self) {
1016        let ptr = self.as_ptr().cast::<T>().debug_ensure_aligned();
1017        // SAFETY: The caller ensure the pointee is of type `T` and uphold safety for `drop_in_place`.
1018        unsafe {
1019            ptr.drop_in_place();
1020        }
1021    }
1022
1023    /// Gets the underlying pointer, erasing the associated lifetime.
1024    ///
1025    /// If possible, it is strongly encouraged to use the other more type-safe functions
1026    /// over this function.
1027    #[inline]
1028    pub fn as_ptr(&self) -> *mut u8 {
1029        self.0.as_ptr()
1030    }
1031
1032    /// Gets an immutable pointer from this owned pointer.
1033    #[inline]
1034    pub fn as_ref(&self) -> Ptr<'_, A> {
1035        // SAFETY: The `Owning` type's guarantees about the validity of this pointer are a superset of `Ptr` s guarantees
1036        unsafe { Ptr::new(self.0) }
1037    }
1038
1039    /// Gets a mutable pointer from this owned pointer.
1040    #[inline]
1041    pub fn as_mut(&mut self) -> PtrMut<'_, A> {
1042        // SAFETY: The `Owning` type's guarantees about the validity of this pointer are a superset of `Ptr` s guarantees
1043        unsafe { PtrMut::new(self.0) }
1044    }
1045}
1046
1047impl<'a> OwningPtr<'a, Unaligned> {
1048    /// Consumes the [`OwningPtr`] to obtain ownership of the underlying data of type `T`.
1049    ///
1050    /// # Safety
1051    /// - `T` must be the erased pointee type for this [`OwningPtr`].
1052    pub unsafe fn read_unaligned<T>(self) -> T {
1053        let ptr = self.as_ptr().cast::<T>();
1054        // SAFETY: The caller ensure the pointee is of type `T` and uphold safety for `read_unaligned`.
1055        unsafe { ptr.read_unaligned() }
1056    }
1057}
1058
1059/// Conceptually equivalent to `&'a [T]` but with length information cut out for performance reasons
1060pub struct ThinSlicePtr<'a, T> {
1061    ptr: NonNull<T>,
1062    #[cfg(debug_assertions)]
1063    len: usize,
1064    _marker: PhantomData<&'a [T]>,
1065}
1066
1067impl<'a, T> ThinSlicePtr<'a, T> {
1068    #[inline]
1069    /// Indexes the slice without doing bounds checks
1070    ///
1071    /// # Safety
1072    /// `index` must be in-bounds.
1073    pub unsafe fn get(self, index: usize) -> &'a T {
1074        #[cfg(debug_assertions)]
1075        debug_assert!(index < self.len);
1076
1077        let ptr = self.ptr.as_ptr();
1078        // SAFETY: `index` is in-bounds so the resulting pointer is valid to dereference.
1079        unsafe { &*ptr.add(index) }
1080    }
1081}
1082
1083impl<'a, T> Clone for ThinSlicePtr<'a, T> {
1084    fn clone(&self) -> Self {
1085        *self
1086    }
1087}
1088
1089impl<'a, T> Copy for ThinSlicePtr<'a, T> {}
1090
1091impl<'a, T> From<&'a [T]> for ThinSlicePtr<'a, T> {
1092    #[inline]
1093    fn from(slice: &'a [T]) -> Self {
1094        let ptr = slice.as_ptr().cast_mut();
1095        Self {
1096            // SAFETY: a reference can never be null
1097            ptr: unsafe { NonNull::new_unchecked(ptr.debug_ensure_aligned()) },
1098            #[cfg(debug_assertions)]
1099            len: slice.len(),
1100            _marker: PhantomData,
1101        }
1102    }
1103}
1104
1105/// Creates a dangling pointer with specified alignment.
1106/// See [`NonNull::dangling`].
1107pub const fn dangling_with_align(align: NonZeroUsize) -> NonNull<u8> {
1108    debug_assert!(align.is_power_of_two(), "Alignment must be power of two.");
1109    // SAFETY: The pointer will not be null, since it was created
1110    // from the address of a `NonZero<usize>`.
1111    // TODO: use https://doc.rust-lang.org/std/ptr/struct.NonNull.html#method.with_addr once stabilized
1112    unsafe { NonNull::new_unchecked(ptr::null_mut::<u8>().wrapping_add(align.get())) }
1113}
1114
1115mod private {
1116    use core::cell::UnsafeCell;
1117
1118    pub trait SealedUnsafeCell {}
1119    impl<'a, T> SealedUnsafeCell for &'a UnsafeCell<T> {}
1120}
1121
1122/// Extension trait for helper methods on [`UnsafeCell`]
1123pub trait UnsafeCellDeref<'a, T>: private::SealedUnsafeCell {
1124    /// # Safety
1125    /// - The returned value must be unique and not alias any mutable or immutable references to the contents of the [`UnsafeCell`].
1126    /// - At all times, you must avoid data races. If multiple threads have access to the same [`UnsafeCell`], then any writes must have a proper happens-before relation to all other accesses or use atomics ([`UnsafeCell`] docs for reference).
1127    unsafe fn deref_mut(self) -> &'a mut T;
1128
1129    /// # Safety
1130    /// - For the lifetime `'a` of the returned value you must not construct a mutable reference to the contents of the [`UnsafeCell`].
1131    /// - At all times, you must avoid data races. If multiple threads have access to the same [`UnsafeCell`], then any writes must have a proper happens-before relation to all other accesses or use atomics ([`UnsafeCell`] docs for reference).
1132    unsafe fn deref(self) -> &'a T;
1133
1134    /// Returns a copy of the contained value.
1135    ///
1136    /// # Safety
1137    /// - The [`UnsafeCell`] must not currently have a mutable reference to its content.
1138    /// - At all times, you must avoid data races. If multiple threads have access to the same [`UnsafeCell`], then any writes must have a proper happens-before relation to all other accesses or use atomics ([`UnsafeCell`] docs for reference).
1139    unsafe fn read(self) -> T
1140    where
1141        T: Copy;
1142}
1143
1144impl<'a, T> UnsafeCellDeref<'a, T> for &'a UnsafeCell<T> {
1145    #[inline]
1146    unsafe fn deref_mut(self) -> &'a mut T {
1147        // SAFETY: The caller upholds the alias rules.
1148        unsafe { &mut *self.get() }
1149    }
1150    #[inline]
1151    unsafe fn deref(self) -> &'a T {
1152        // SAFETY: The caller upholds the alias rules.
1153        unsafe { &*self.get() }
1154    }
1155
1156    #[inline]
1157    unsafe fn read(self) -> T
1158    where
1159        T: Copy,
1160    {
1161        // SAFETY: The caller upholds the alias rules.
1162        unsafe { self.get().read() }
1163    }
1164}
1165
1166trait DebugEnsureAligned {
1167    fn debug_ensure_aligned(self) -> Self;
1168}
1169
1170// Disable this for miri runs as it already checks if pointer to reference
1171// casts are properly aligned.
1172#[cfg(all(debug_assertions, not(miri)))]
1173impl<T: Sized> DebugEnsureAligned for *mut T {
1174    #[track_caller]
1175    fn debug_ensure_aligned(self) -> Self {
1176        let align = align_of::<T>();
1177        // Implementation shamelessly borrowed from the currently unstable
1178        // ptr.is_aligned_to.
1179        //
1180        // Replace once https://github.com/rust-lang/rust/issues/96284 is stable.
1181        assert_eq!(
1182            self as usize & (align - 1),
1183            0,
1184            "pointer is not aligned. Address {:p} does not have alignment {} for type {}",
1185            self,
1186            align,
1187            core::any::type_name::<T>()
1188        );
1189        self
1190    }
1191}
1192
1193#[cfg(any(not(debug_assertions), miri))]
1194impl<T: Sized> DebugEnsureAligned for *mut T {
1195    #[inline(always)]
1196    fn debug_ensure_aligned(self) -> Self {
1197        self
1198    }
1199}
1200
1201/// Safely converts a owned value into a [`MovingPtr`] while minimizing the number of stack copies.
1202///
1203/// This cannot be used as expression and must be used as a statement. Internally this macro works via variable shadowing.
1204#[macro_export]
1205macro_rules! move_as_ptr {
1206    ($value: ident) => {
1207        let mut $value = core::mem::MaybeUninit::new($value);
1208        // SAFETY:
1209        // - This macro shadows a MaybeUninit value that took ownership of the original value.
1210        //   it is impossible to refer to the original value, preventing further access after
1211        //   the `MovingPtr` has been used. `MaybeUninit` also prevents the compiler from
1212        //   dropping the original value.
1213        let $value = unsafe { $crate::MovingPtr::from_value(&mut $value) };
1214    };
1215}
1216
1217/// Helper macro used by [`deconstruct_moving_ptr`] to to extract
1218/// the pattern from `field: pattern` or `field` shorthand.
1219#[macro_export]
1220#[doc(hidden)]
1221macro_rules! get_pattern {
1222    ($field_index:tt) => {
1223        $field_index
1224    };
1225    ($field_index:tt: $pattern:pat) => {
1226        $pattern
1227    };
1228}
1229
1230/// Deconstructs a [`MovingPtr`] into its individual fields.
1231///
1232/// This consumes the [`MovingPtr`] and hands out [`MovingPtr`] wrappers around
1233/// pointers to each of its fields. The value will *not* be dropped.
1234///
1235/// The macro should wrap a `let` expression with a struct pattern.
1236/// It does not support matching tuples by position,
1237/// so for tuple structs you should use `0: pat` syntax.
1238///
1239/// For tuples themselves, pass the identifier `tuple` instead of the struct name,
1240/// like `let tuple { 0: pat0, 1: pat1 } = value`.
1241///
1242/// This can also project into `MaybeUninit`.
1243/// Wrap the type name or `tuple` with `MaybeUninit::<_>`,
1244/// and the macro will deconstruct a `MovingPtr<MaybeUninit<ParentType>>`
1245/// into `MovingPtr<MaybeUninit<FieldType>>` values.
1246///
1247/// # Examples
1248///
1249/// ## Structs
1250///
1251/// ```
1252/// use core::mem::{offset_of, MaybeUninit};
1253/// use bevy_ptr::{MovingPtr, move_as_ptr};
1254/// # use bevy_ptr::Unaligned;
1255/// # struct FieldAType(usize);
1256/// # struct FieldBType(usize);
1257/// # struct FieldCType(usize);
1258///
1259/// # pub struct Parent {
1260/// #  pub field_a: FieldAType,
1261/// #  pub field_b: FieldBType,
1262/// #  pub field_c: FieldCType,
1263/// # }
1264///
1265/// let parent = Parent {
1266///   field_a: FieldAType(11),
1267///   field_b: FieldBType(22),
1268///   field_c: FieldCType(33),
1269/// };
1270///
1271/// let mut target_a = FieldAType(101);
1272/// let mut target_b = FieldBType(102);
1273/// let mut target_c = FieldCType(103);
1274///
1275/// // Converts `parent` into a `MovingPtr`
1276/// move_as_ptr!(parent);
1277///
1278/// // The field names must match the name used in the type definition.
1279/// // Each one will be a `MovingPtr` of the field's type.
1280/// bevy_ptr::deconstruct_moving_ptr!({
1281///   let Parent { field_a, field_b, field_c } = parent;
1282/// });
1283///
1284/// field_a.assign_to(&mut target_a);
1285/// field_b.assign_to(&mut target_b);
1286/// field_c.assign_to(&mut target_c);
1287///
1288/// assert_eq!(target_a.0, 11);
1289/// assert_eq!(target_b.0, 22);
1290/// assert_eq!(target_c.0, 33);
1291/// ```
1292///
1293/// ## Tuples
1294///
1295/// ```
1296/// use core::mem::{offset_of, MaybeUninit};
1297/// use bevy_ptr::{MovingPtr, move_as_ptr};
1298/// # use bevy_ptr::Unaligned;
1299/// # struct FieldAType(usize);
1300/// # struct FieldBType(usize);
1301/// # struct FieldCType(usize);
1302///
1303/// # pub struct Parent {
1304/// #   pub field_a: FieldAType,
1305/// #  pub field_b: FieldBType,
1306/// #  pub field_c: FieldCType,
1307/// # }
1308///
1309/// let parent = (
1310///   FieldAType(11),
1311///   FieldBType(22),
1312///   FieldCType(33),
1313/// );
1314///
1315/// let mut target_a = FieldAType(101);
1316/// let mut target_b = FieldBType(102);
1317/// let mut target_c = FieldCType(103);
1318///
1319/// // Converts `parent` into a `MovingPtr`
1320/// move_as_ptr!(parent);
1321///
1322/// // The field names must match the name used in the type definition.
1323/// // Each one will be a `MovingPtr` of the field's type.
1324/// bevy_ptr::deconstruct_moving_ptr!({
1325///   let tuple { 0: field_a, 1: field_b, 2: field_c } = parent;
1326/// });
1327///
1328/// field_a.assign_to(&mut target_a);
1329/// field_b.assign_to(&mut target_b);
1330/// field_c.assign_to(&mut target_c);
1331///
1332/// assert_eq!(target_a.0, 11);
1333/// assert_eq!(target_b.0, 22);
1334/// assert_eq!(target_c.0, 33);
1335/// ```
1336///
1337/// ## `MaybeUninit`
1338///
1339/// ```
1340/// use core::mem::{offset_of, MaybeUninit};
1341/// use bevy_ptr::{MovingPtr, move_as_ptr};
1342/// # use bevy_ptr::Unaligned;
1343/// # struct FieldAType(usize);
1344/// # struct FieldBType(usize);
1345/// # struct FieldCType(usize);
1346///
1347/// # pub struct Parent {
1348/// #  pub field_a: FieldAType,
1349/// #  pub field_b: FieldBType,
1350/// #  pub field_c: FieldCType,
1351/// # }
1352///
1353/// let parent = MaybeUninit::new(Parent {
1354///   field_a: FieldAType(11),
1355///   field_b: FieldBType(22),
1356///   field_c: FieldCType(33),
1357/// });
1358///
1359/// let mut target_a = MaybeUninit::new(FieldAType(101));
1360/// let mut target_b = MaybeUninit::new(FieldBType(102));
1361/// let mut target_c = MaybeUninit::new(FieldCType(103));
1362///
1363/// // Converts `parent` into a `MovingPtr`
1364/// move_as_ptr!(parent);
1365///
1366/// // The field names must match the name used in the type definition.
1367/// // Each one will be a `MovingPtr` of the field's type.
1368/// bevy_ptr::deconstruct_moving_ptr!({
1369///   let MaybeUninit::<Parent> { field_a, field_b, field_c } = parent;
1370/// });
1371///
1372/// field_a.assign_to(&mut target_a);
1373/// field_b.assign_to(&mut target_b);
1374/// field_c.assign_to(&mut target_c);
1375///
1376/// unsafe {
1377///   assert_eq!(target_a.assume_init().0, 11);
1378///   assert_eq!(target_b.assume_init().0, 22);
1379///   assert_eq!(target_c.assume_init().0, 33);
1380/// }
1381/// ```
1382///
1383/// [`assign_to`]: MovingPtr::assign_to
1384#[macro_export]
1385macro_rules! deconstruct_moving_ptr {
1386    ({ let tuple { $($field_index:tt: $pattern:pat),* $(,)? } = $ptr:expr ;}) => {
1387        // Specify the type to make sure the `mem::forget` doesn't forget a mere `&mut MovingPtr`
1388        let mut ptr: $crate::MovingPtr<_, _> = $ptr;
1389        let _ = || {
1390            let value = &mut *ptr;
1391            // Ensure that each field index exists and is mentioned only once
1392            // Ensure that the struct is not `repr(packed)` and that we may take references to fields
1393            core::hint::black_box(($(&mut value.$field_index,)*));
1394            // Ensure that `ptr` is a tuple and not something that derefs to it
1395            // Ensure that the number of patterns matches the number of fields
1396            fn unreachable<T>(_index: usize) -> T {
1397                unreachable!()
1398            }
1399            *value = ($(unreachable($field_index),)*);
1400        };
1401        // SAFETY:
1402        // - `f` does a raw pointer offset, which always returns a non-null pointer to a field inside `T`
1403        // - The struct is not `repr(packed)`, since otherwise the block of code above would fail compilation
1404        // - `mem::forget` is called on `self` immediately after these calls
1405        // - Each field is distinct, since otherwise the block of code above would fail compilation
1406        $(let $pattern = unsafe { ptr.move_field(|f| &raw mut (*f).$field_index) };)*
1407        core::mem::forget(ptr);
1408    };
1409    ({ let MaybeUninit::<tuple> { $($field_index:tt: $pattern:pat),* $(,)? } = $ptr:expr ;}) => {
1410        // Specify the type to make sure the `mem::forget` doesn't forget a mere `&mut MovingPtr`
1411        let mut ptr: $crate::MovingPtr<core::mem::MaybeUninit<_>, _> = $ptr;
1412        let _ = || {
1413            // SAFETY: This closure is never called
1414            let value = unsafe { ptr.assume_init_mut() };
1415            // Ensure that each field index exists and is mentioned only once
1416            // Ensure that the struct is not `repr(packed)` and that we may take references to fields
1417            core::hint::black_box(($(&mut value.$field_index,)*));
1418            // Ensure that `ptr` is a tuple and not something that derefs to it
1419            // Ensure that the number of patterns matches the number of fields
1420            fn unreachable<T>(_index: usize) -> T {
1421                unreachable!()
1422            }
1423            *value = ($(unreachable($field_index),)*);
1424        };
1425        // SAFETY:
1426        // - `f` does a raw pointer offset, which always returns a non-null pointer to a field inside `T`
1427        // - The struct is not `repr(packed)`, since otherwise the block of code above would fail compilation
1428        // - `mem::forget` is called on `self` immediately after these calls
1429        // - Each field is distinct, since otherwise the block of code above would fail compilation
1430        $(let $pattern = unsafe { ptr.move_maybe_uninit_field(|f| &raw mut (*f).$field_index) };)*
1431        core::mem::forget(ptr);
1432    };
1433    ({ let $struct_name:ident { $($field_index:tt$(: $pattern:pat)?),* $(,)? } = $ptr:expr ;}) => {
1434        // Specify the type to make sure the `mem::forget` doesn't forget a mere `&mut MovingPtr`
1435        let mut ptr: $crate::MovingPtr<_, _> = $ptr;
1436        let _ = || {
1437            let value = &mut *ptr;
1438            // Ensure that each field index exists is mentioned only once
1439            // Ensure that each field is on the struct and not accessed using autoref
1440            let $struct_name { $($field_index: _),* } = value;
1441            // Ensure that the struct is not `repr(packed)` and that we may take references to fields
1442            core::hint::black_box(($(&mut value.$field_index),*));
1443            // Ensure that `ptr` is a `$struct_name` and not just something that derefs to it
1444            let value: *mut _ = value;
1445            // SAFETY: This closure is never called
1446            $struct_name { ..unsafe { value.read() } };
1447        };
1448        // SAFETY:
1449        // - `f` does a raw pointer offset, which always returns a non-null pointer to a field inside `T`
1450        // - The struct is not `repr(packed)`, since otherwise the block of code above would fail compilation
1451        // - `mem::forget` is called on `self` immediately after these calls
1452        // - Each field is distinct, since otherwise the block of code above would fail compilation
1453        $(let $crate::get_pattern!($field_index$(: $pattern)?) = unsafe { ptr.move_field(|f| &raw mut (*f).$field_index) };)*
1454        core::mem::forget(ptr);
1455    };
1456    ({ let MaybeUninit::<$struct_name:ident> { $($field_index:tt$(: $pattern:pat)?),* $(,)? } = $ptr:expr ;}) => {
1457        // Specify the type to make sure the `mem::forget` doesn't forget a mere `&mut MovingPtr`
1458        let mut ptr: $crate::MovingPtr<core::mem::MaybeUninit<_>, _> = $ptr;
1459        let _ = || {
1460            // SAFETY: This closure is never called
1461            let value = unsafe { ptr.assume_init_mut() };
1462            // Ensure that each field index exists is mentioned only once
1463            // Ensure that each field is on the struct and not accessed using autoref
1464            let $struct_name { $($field_index: _),* } = value;
1465            // Ensure that the struct is not `repr(packed)` and that we may take references to fields
1466            core::hint::black_box(($(&mut value.$field_index),*));
1467            // Ensure that `ptr` is a `$struct_name` and not just something that derefs to it
1468            let value: *mut _ = value;
1469            // SAFETY: This closure is never called
1470            $struct_name { ..unsafe { value.read() } };
1471        };
1472        // SAFETY:
1473        // - `f` does a raw pointer offset, which always returns a non-null pointer to a field inside `T`
1474        // - The struct is not `repr(packed)`, since otherwise the block of code above would fail compilation
1475        // - `mem::forget` is called on `self` immediately after these calls
1476        // - Each field is distinct, since otherwise the block of code above would fail compilation
1477        $(let $crate::get_pattern!($field_index$(: $pattern)?) = unsafe { ptr.move_maybe_uninit_field(|f| &raw mut (*f).$field_index) };)*
1478        core::mem::forget(ptr);
1479    };
1480}