Struct bevy::ecs::ptr::OwningPtr

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

Type-erased Box-like pointer to some unknown type chosen when constructing this type. Conceptually represents ownership of whatever data is being pointed to and so is responsible for calling its Drop impl. 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” 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 points to a valid value of whatever the pointee type is.
  • The lifetime 'a accurately represents how long the pointer is valid for.
  • Must be sufficiently aligned for the unknown pointee type.

It may be helpful to think of this type as similar to &'a mut ManuallyDrop<dyn Any> but without the metadata and able to point to data that does not correspond to a Rust type.

Implementations§

§

impl<'a> OwningPtr<'a>

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

Removes the alignment requirement of this pointer

§

impl<A> OwningPtr<'_, A>
where A: IsAligned,

pub unsafe fn byte_offset(self, count: isize) -> OwningPtr<'_, A>

Calculates the offset from a pointer. As the pointer is type-erased, there is no size information available. The provided count parameter is in raw bytes.

See also: ptr::offset

§Safety
  • The offset cannot make the existing ptr null, or take it out of bounds for its allocation.
  • If the A type parameter is Aligned then the offset must not make the resulting pointer be unaligned for the pointee type.
  • The value pointed by the resulting pointer must outlive the lifetime of this pointer.

pub unsafe fn byte_add(self, count: usize) -> OwningPtr<'_, A>

Calculates the offset from a pointer (convenience for .offset(count as isize)). As the pointer is type-erased, there is no size information available. The provided count parameter is in raw bytes.

See also: ptr::add

§Safety
  • The offset cannot make the existing ptr null, or take it out of bounds for its allocation.
  • If the A type parameter is Aligned then the offset must not make the resulting pointer be unaligned for the pointee type.
  • The value pointed by the resulting pointer must outlive the lifetime of this pointer.
§

impl<'a> OwningPtr<'a>

pub fn make<T, F, R>(val: T, f: F) -> R
where F: FnOnce(OwningPtr<'_>) -> R,

Consumes a value and creates an OwningPtr to it while ensuring a double drop does not happen.

§

impl<'a, A> OwningPtr<'a, A>
where A: IsAligned,

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

Creates a new instance from a raw pointer.

§Safety
  • inner must point to valid value of whatever the pointee type is.
  • If the A type parameter is Aligned then inner must be sufficiently aligned for the pointee type.
  • inner must have correct provenance to allow read and writes of the pointee type.
  • The lifetime 'a must be constrained such that this OwningPtr will stay valid and nothing else can read or mutate the pointee while this OwningPtr is live.
Examples found in repository?
examples/ecs/dynamic.rs (line 202)
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
fn to_owning_ptrs(components: &mut [Vec<u64>]) -> Vec<OwningPtr<Aligned>> {
    components
        .iter_mut()
        .map(|data| {
            let ptr = data.as_mut_ptr();
            // SAFETY:
            // - Pointers are guaranteed to be non-null
            // - Memory pointed to won't be dropped until `components` is dropped
            unsafe {
                let non_null = NonNull::new_unchecked(ptr.cast());
                OwningPtr::new(non_null)
            }
        })
        .collect()
}

pub unsafe fn read<T>(self) -> T

Consumes the OwningPtr to obtain ownership of the underlying data of type T.

§Safety
  • T must be the erased pointee type for this OwningPtr.
  • If the type parameter A is Unaligned then this pointer must be sufficiently aligned for the pointee type T.

pub unsafe fn drop_as<T>(self)

Consumes the OwningPtr to drop the underlying data of type T.

§Safety
  • T must be the erased pointee type for this OwningPtr.
  • If the type parameter A is Unaligned then this pointer must be sufficiently aligned for the pointee type T.

pub fn as_ptr(&self) -> *mut u8

Gets the underlying pointer, erasing the associated lifetime.

If possible, it is strongly encouraged to use the other more type-safe functions over this function.

pub fn as_ref(&self) -> Ptr<'_, A>

Gets an immutable pointer from this owned pointer.

pub fn as_mut(&mut self) -> PtrMut<'_, A>

Gets a mutable pointer from this owned pointer.

§

impl<'a> OwningPtr<'a, Unaligned>

pub unsafe fn read_unaligned<T>(self) -> T

Consumes the OwningPtr to obtain ownership of the underlying data of type T.

§Safety
  • T must be the erased pointee type for this OwningPtr.

Trait Implementations§

§

impl<'a, A> Debug for OwningPtr<'a, A>
where A: Debug + IsAligned,

§

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

Formats the value using the given formatter. Read more
§

impl<'a, A> From<OwningPtr<'a, A>> for NonNull<u8>
where A: IsAligned,

§

fn from(ptr: OwningPtr<'a, A>) -> NonNull<u8>

Converts to this type from the input type.
§

impl<A> Pointer for OwningPtr<'_, A>
where A: IsAligned,

§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<'a, A> Freeze for OwningPtr<'a, A>

§

impl<'a, A> RefUnwindSafe for OwningPtr<'a, A>
where A: RefUnwindSafe,

§

impl<'a, A = Aligned> !Send for OwningPtr<'a, A>

§

impl<'a, A = Aligned> !Sync for OwningPtr<'a, A>

§

impl<'a, A> Unpin for OwningPtr<'a, A>
where A: Unpin,

§

impl<'a, A = Aligned> !UnwindSafe for OwningPtr<'a, A>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
§

impl<T, U> AsBindGroupShaderType<U> for T
where U: ShaderType, &'a T: for<'a> Into<U>,

§

fn as_bind_group_shader_type(&self, _images: &RenderAssets<GpuImage>) -> U

Return the T ShaderType for self. When used in AsBindGroup derives, it is safe to assume that all images in self exist.
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
§

impl<T> Downcast<T> for T

§

fn downcast(&self) -> &T

§

impl<T> Downcast for T
where T: Any,

§

fn into_any(self: Box<T>) -> Box<dyn Any>

Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait.
§

fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>

Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait.
§

fn as_any(&self) -> &(dyn Any + 'static)

Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s.
§

fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)

Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s.
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<S> FromSample<S> for S

§

fn from_sample_(s: S) -> S

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> IntoEither for T

source§

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more
§

impl<F, T> IntoSample<T> for F
where T: FromSample<F>,

§

fn into_sample(self) -> T

§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T> Same for T

§

type Output = T

Should always be Self
§

impl<T, U> ToSample<U> for T
where U: FromSample<T>,

§

fn to_sample_(self) -> U

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<T> Upcast<T> for T

§

fn upcast(&self) -> Option<&T>

§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
§

impl<S, T> Duplex<S> for T
where T: FromSample<S> + ToSample<S>,