Struct Ptr

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

Type-erased borrow of some unknown type chosen when constructing this type.

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

• It should be considered immutable: its target must not be changed while this pointer is alive.
• 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 dyn Any but without the metadata and able to point to data that does not correspond to a Rust type.

Implementations

impl<'a> Ptr<'a>

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

Removes the alignment requirement of this pointer

impl<A> Ptr<'_, A>

where A: IsAligned,

pub unsafe fn byte_offset(self, count: isize) -> Ptr<'_, 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) -> Ptr<'_, 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, A> Ptr<'a, A>

where A: IsAligned,

pub unsafe fn new(inner: NonNull<u8>) -> Ptr<'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 reads of the pointee type.
• The lifetime 'a must be constrained such that this Ptr will stay valid and nothing can mutate the pointee while this Ptr is live except through an UnsafeCell.

pub unsafe fn assert_unique(self) -> PtrMut<'a, A>

Transforms this Ptr into an PtrMut

Safety

• The data pointed to by this Ptr must be valid for writes.
• There must be no active references (mutable or otherwise) to the data underlying this Ptr.
• Another PtrMut for the same Ptr must not be created until the first is dropped.

Examples found in repository

examples/ecs/dynamic.rs (line 173)

fn main() {
    let mut world = World::new();
    let mut lines = std::io::stdin().lines();
    let mut component_names = HashMap::<String, ComponentId>::new();
    let mut component_info = HashMap::<ComponentId, ComponentInfo>::new();

    println!("{PROMPT}");
    loop {
        print!("\n> ");
        let _ = std::io::stdout().flush();
        let Some(Ok(line)) = lines.next() else {
            return;
        };

        if line.is_empty() {
            return;
        };

        let Some((first, rest)) = line.trim().split_once(|c: char| c.is_whitespace()) else {
            match &line.chars().next() {
                Some('c') => println!("{COMPONENT_PROMPT}"),
                Some('s') => println!("{ENTITY_PROMPT}"),
                Some('q') => println!("{QUERY_PROMPT}"),
                _ => println!("{PROMPT}"),
            }
            continue;
        };

        match &first[0..1] {
            "c" => {
                rest.split(',').for_each(|component| {
                    let mut component = component.split_whitespace();
                    let Some(name) = component.next() else {
                        return;
                    };
                    let size = match component.next().map(str::parse) {
                        Some(Ok(size)) => size,
                        _ => 0,
                    };
                    // Register our new component to the world with a layout specified by it's size
                    // SAFETY: [u64] is Send + Sync
                    let id = world.register_component_with_descriptor(unsafe {
                        ComponentDescriptor::new_with_layout(
                            name.to_string(),
                            StorageType::Table,
                            Layout::array::<u64>(size).unwrap(),
                            None,
                            true,
                            ComponentCloneBehavior::Default,
                        )
                    });
                    let Some(info) = world.components().get_info(id) else {
                        return;
                    };
                    component_names.insert(name.to_string(), id);
                    component_info.insert(id, info.clone());
                    println!("Component {} created with id: {}", name, id.index());
                });
            }
            "s" => {
                let mut to_insert_ids = Vec::new();
                let mut to_insert_data = Vec::new();
                rest.split(',').for_each(|component| {
                    let mut component = component.split_whitespace();
                    let Some(name) = component.next() else {
                        return;
                    };

                    // Get the id for the component with the given name
                    let Some(&id) = component_names.get(name) else {
                        println!("Component {name} does not exist");
                        return;
                    };

                    // Calculate the length for the array based on the layout created for this component id
                    let info = world.components().get_info(id).unwrap();
                    let len = info.layout().size() / size_of::<u64>();
                    let mut values: Vec<u64> = component
                        .take(len)
                        .filter_map(|value| value.parse::<u64>().ok())
                        .collect();
                    values.resize(len, 0);

                    // Collect the id and array to be inserted onto our entity
                    to_insert_ids.push(id);
                    to_insert_data.push(values);
                });

                let mut entity = world.spawn_empty();

                // Construct an `OwningPtr` for each component in `to_insert_data`
                let to_insert_ptr = to_owning_ptrs(&mut to_insert_data);

                // SAFETY:
                // - Component ids have been taken from the same world
                // - Each array is created to the layout specified in the world
                unsafe {
                    entity.insert_by_ids(&to_insert_ids, to_insert_ptr.into_iter());
                }

                println!("Entity spawned with id: {}", entity.id());
            }
            "q" => {
                let mut builder = QueryBuilder::<FilteredEntityMut>::new(&mut world);
                parse_query(rest, &mut builder, &component_names);
                let mut query = builder.build();
                query.iter_mut(&mut world).for_each(|filtered_entity| {
                    let terms = filtered_entity
                        .access()
                        .try_iter_component_access()
                        .unwrap()
                        .map(|component_access| {
                            let id = *component_access.index();
                            let ptr = filtered_entity.get_by_id(id).unwrap();
                            let info = component_info.get(&id).unwrap();
                            let len = info.layout().size() / size_of::<u64>();

                            // SAFETY:
                            // - All components are created with layout [u64]
                            // - len is calculated from the component descriptor
                            let data = unsafe {
                                std::slice::from_raw_parts_mut(
                                    ptr.assert_unique().as_ptr().cast::<u64>(),
                                    len,
                                )
                            };

                            // If we have write access, increment each value once
                            if matches!(component_access, ComponentAccessKind::Exclusive(_)) {
                                data.iter_mut().for_each(|data| {
                                    *data += 1;
                                });
                            }

                            format!("{}: {:?}", info.name(), data[0..len].to_vec())
                        })
                        .collect::<Vec<_>>()
                        .join(", ");

                    println!("{}: {}", filtered_entity.id(), terms);
                });
            }
            _ => continue,
        }
    }
}

pub unsafe fn deref<T>(self) -> &'a T

Transforms this Ptr<T> into a &T with the same lifetime

Safety

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

Examples found in repository

examples/stress_tests/many_components.rs (line 53)

fn base_system(access_components: In<Vec<ComponentId>>, mut query: Query<FilteredEntityMut>) {
    #[cfg(feature = "trace")]
    let _span = tracing::info_span!("base_system", components = ?access_components.0, count = query.iter().len()).entered();

    for mut filtered_entity in &mut query {
        // We calculate Faulhaber's formula mod 256 with n = value and p = exponent.
        // See https://en.wikipedia.org/wiki/Faulhaber%27s_formula
        // The time is takes to compute this depends on the number of entities and the values in
        // each entity. This is to ensure that each system takes a different amount of time.
        let mut total: Wrapping<u8> = Wrapping(0);
        let mut exponent: u32 = 1;
        for component_id in &access_components.0 {
            // find the value of the component
            let ptr = filtered_entity.get_by_id(*component_id).unwrap();

            // SAFETY: All components have a u8 layout
            let value: u8 = unsafe { *ptr.deref::<u8>() };

            for i in 0..=value {
                let mut product = Wrapping(1);
                for _ in 1..=exponent {
                    product *= Wrapping(i);
                }
                total += product;
            }
            exponent += 1;
        }

        // we assign this value to all the components we can write to
        for component_id in &access_components.0 {
            if let Some(ptr) = filtered_entity.get_mut_by_id(*component_id) {
                // SAFETY: All components have a u8 layout
                unsafe {
                    let mut value = ptr.with_type::<u8>();
                    *value = total.0;
                }
            }
        }
    }
}

pub fn as_ptr(self) -> *mut u8

Gets the underlying pointer, erasing the associated lifetime.

If possible, it is strongly encouraged to use deref over this function, as it retains the lifetime.

Trait Implementations

impl<'a, A> Clone for Ptr<'a, A>

where A: Clone + IsAligned,

fn clone(&self) -> Ptr<'a, A>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Ptr<'_>

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

Formats the value using the given formatter.

impl Debug for Ptr<'_, Unaligned>

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

Formats the value using the given formatter.

impl<'a, T> From<&'a T> for Ptr<'a>

where T: ?Sized,

fn from(val: &'a T) -> Ptr<'a>

Converts to this type from the input type.

impl<'a, A> From<Ptr<'a, A>> for NonNull<u8>

where A: IsAligned,

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

Converts to this type from the input type.

impl<A> Pointer for Ptr<'_, A>

where A: IsAligned,

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

Formats the value using the given formatter.

impl<'a, A> Copy for Ptr<'a, A>

where A: Copy + IsAligned,