Struct MovingPtr 

pub struct MovingPtr<'a, T, A = Aligned>(/* private fields */)
where
    A: IsAligned;

A Box-like pointer for moving a value to a new memory location without needing to pass by value.

Conceptually represents ownership of whatever data is being pointed to and will call its Drop impl upon being dropped. This pointer is not responsible for freeing the memory pointed to by this pointer as it may be pointing to an element in a Vec or to a local in a function etc.

This type tries to act “borrow-like” which means that:

• Pointer should be considered exclusive and mutable. It cannot be cloned as this would lead to aliased mutability and potentially use after free bugs.
• It must always point to a valid value of whatever the pointee type is.
• The lifetime 'a accurately represents how long the pointer is valid for.
• It does not support pointer arithmetic in any way.
• If A is Aligned, the pointer must always be properly aligned for the type T.

A value can be deconstructed into its fields via deconstruct_moving_ptr, see it’s documentation for an example on how to use it.

Implementations

impl<'a, T> MovingPtr<'a, T>

pub fn to_unaligned(self) -> MovingPtr<'a, T, Unaligned>

Removes the alignment requirement of this pointer

pub unsafe fn from_value(value: &'a mut MaybeUninit<T>) -> MovingPtr<'a, T>

Creates a MovingPtr from a provided value of type T.

For a safer alternative, it is strongly advised to use move_as_ptr where possible.

Safety

• value must store a properly initialized value of type T.
• Once the returned MovingPtr has been used, value must be treated as it were uninitialized unless it was explicitly leaked via core::mem::forget.

impl<'a, T, A> MovingPtr<'a, T, A>

where A: IsAligned,

pub unsafe fn new(inner: NonNull<T>) -> MovingPtr<'a, T, A>

Creates a new instance from a raw pointer.

For a safer alternative, it is strongly advised to use move_as_ptr where possible.

Safety

• inner must point to valid value of T.
• If the A type parameter is Aligned then inner must be be properly aligned for T.
• inner must have correct provenance to allow read and writes of the pointee type.
• The lifetime 'a must be constrained such that this MovingPtr will stay valid and nothing else can read or mutate the pointee while this MovingPtr is live.

pub fn partial_move<R>( self, f: impl FnOnce(MovingPtr<'_, T, A>) -> R, ) -> (MovingPtr<'a, MaybeUninit<T>, A>, R)

Partially moves out some fields inside of self.

The partially returned value is returned back pointing to MaybeUninit<T>.

While calling this function is safe, care must be taken with the returned MovingPtr as it points to a value that may no longer be completely valid.

Example

use core::mem::{offset_of, MaybeUninit, forget};
use bevy_ptr::{MovingPtr, move_as_ptr};

struct Parent {
  field_a: FieldAType,
  field_b: FieldBType,
  field_c: FieldCType,
}


// Converts `parent` into a `MovingPtr`
move_as_ptr!(parent);

// SAFETY:
// - `field_a` and `field_b` are both unique.
let (partial_parent, ()) = MovingPtr::partial_move(parent, |parent_ptr| unsafe {
  bevy_ptr::deconstruct_moving_ptr!({
    let Parent { field_a, field_b, field_c } = parent_ptr;
  });
   
  insert(field_a);
  insert(field_b);
  forget(field_c);
});

// Move the rest of fields out of the parent.
// SAFETY:
// - `field_c` is by itself unique and does not conflict with the previous accesses
//   inside `partial_move`.
unsafe {
  bevy_ptr::deconstruct_moving_ptr!({
    let MaybeUninit::<Parent> { field_a: _, field_b: _, field_c } = partial_parent;
  });

  insert(field_c);
}

pub fn read(self) -> T

Reads the value pointed to by this pointer.

pub unsafe fn write_to(self, dst: *mut T)

Writes the value pointed to by this pointer to a provided location.

This does not drop the value stored at dst and it’s the caller’s responsibility to ensure that it’s properly dropped.

Safety

• dst must be valid for writes.
• If the A type parameter is Aligned then dst must be properly aligned for T.

pub fn assign_to(self, dst: &mut T)

Writes the value pointed to by this pointer into dst.

The value previously stored at dst will be dropped.

pub unsafe fn move_field<U>( &self, f: impl Fn(*mut T) -> *mut U, ) -> MovingPtr<'a, U, A>

Creates a MovingPtr for a specific field within self.

This function is explicitly made for deconstructive moves.

The correct byte_offset for a field can be obtained via core::mem::offset_of.

Safety

• f must return a non-null pointer to a valid field inside T
• If A is Aligned, then T must not be repr(packed)
• self should not be accessed or dropped as if it were a complete value after this function returns. Other fields that have not been moved out of may still be accessed or dropped separately.
• This function cannot alias the field with any other access, including other calls to move_field for the same field, without first calling forget on it first.

A result of the above invariants means that any operation that could cause self to be dropped while the pointers to the fields are held will result in undefined behavior. This requires exctra caution around code that may panic. See the example below for an example of how to safely use this function.

Example

use core::mem::offset_of;
use bevy_ptr::{MovingPtr, move_as_ptr};

struct Parent {
  field_a: FieldAType,
  field_b: FieldBType,
  field_c: FieldCType,
}

let parent = Parent {
   field_a: FieldAType(0),
   field_b: FieldBType(0),
   field_c: FieldCType(0),
};

// Converts `parent` into a `MovingPtr`.
move_as_ptr!(parent);

unsafe {
   let field_a = parent.move_field(|ptr| &raw mut (*ptr).field_a);
   let field_b = parent.move_field(|ptr| &raw mut (*ptr).field_b);
   let field_c = parent.move_field(|ptr| &raw mut (*ptr).field_c);
   // Each call to insert may panic! Ensure that `parent_ptr` cannot be dropped before
   // calling them!
   core::mem::forget(parent);
   insert(field_a);
   insert(field_b);
   insert(field_c);
}

impl<'a, T, A> MovingPtr<'a, MaybeUninit<T>, A>

where A: IsAligned,

pub unsafe fn move_maybe_uninit_field<U>( &self, f: impl Fn(*mut T) -> *mut U, ) -> MovingPtr<'a, MaybeUninit<U>, A>

Creates a MovingPtr for a specific field within self.

This function is explicitly made for deconstructive moves.

The correct byte_offset for a field can be obtained via core::mem::offset_of.

Safety

• f must return a non-null pointer to a valid field inside T
• If A is Aligned, then T must not be repr(packed)
• self should not be accessed or dropped as if it were a complete value after this function returns. Other fields that have not been moved out of may still be accessed or dropped separately.
• This function cannot alias the field with any other access, including other calls to move_field for the same field, without first calling forget on it first.

impl<'a, T, A> MovingPtr<'a, MaybeUninit<T>, A>

where A: IsAligned,

pub unsafe fn assume_init(self) -> MovingPtr<'a, T, A>

Creates a MovingPtr pointing to a valid instance of T.

See also: MaybeUninit::assume_init.

Safety

It’s up to the caller to ensure that the value pointed to by self is really in an initialized state. Calling this when the content is not yet fully initialized causes immediate undefined behavior.

Trait Implementations

impl<T> Debug for MovingPtr<'_, T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Debug for MovingPtr<'_, T, Unaligned>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Deref for MovingPtr<'_, T>

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &<MovingPtr<'_, T> as Deref>::Target

Dereferences the value.

impl<T> DerefMut for MovingPtr<'_, T>

fn deref_mut(&mut self) -> &mut <MovingPtr<'_, T> as Deref>::Target

Mutably dereferences the value.

impl<T, A> Drop for MovingPtr<'_, T, A>

where A: IsAligned,

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, T, A> From<MovingPtr<'a, T, A>> for OwningPtr<'a, A>

where A: IsAligned,

fn from(value: MovingPtr<'a, T, A>) -> OwningPtr<'a, A>

Converts to this type from the input type.

impl<T, A> Pointer for MovingPtr<'_, T, A>

where A: IsAligned,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'a, T> TryFrom<MovingPtr<'a, T, Unaligned>> for MovingPtr<'a, T>

type Error = MovingPtr<'a, T, Unaligned>

The type returned in the event of a conversion error.

fn try_from( value: MovingPtr<'a, T, Unaligned>, ) -> Result<MovingPtr<'a, T>, <MovingPtr<'a, T> as TryFrom<MovingPtr<'a, T, Unaligned>>>::Error>

Performs the conversion.