get_components_mut

[hymm]

Objective

• Add a checked version of EntityMut::get_components_mut and EntityWorldMut::get_components_mut that does not allocate

Solution

• Add a iterator over the access type to QueryData. This is then used to iterate over the pairs of access to check if they are compatible or not.

Testing

• Added a unit test

Bench checked vs unchecked (50000 entities)

#components	unchecked	checked	times slower
2	509 us	959 us	1.88x
5	903 us	3281 us	3.6x
10	1700 us	25369 us	14.9x

so at 10 components each call was taking about 1.06us vs 0.03 us

---

ToDo

• add release note
• add migration guide
• add macro for more benches
• add bench results to pr description
• look into if this will help with uncached queries
• see if we can optimize it a bit

[github-actions]

It looks like your PR has been selected for a highlight in the next release blog post, but you didn't provide a release note.

Please review the instructions for writing release notes, then expand or revise the content in the release notes directory to showcase your changes.

[chescock]

This is a very clever idea! I'm a little curious just how much faster it is than doing a naive check like in #20273.

[chescock]

We could probably ignore resource access for this. We don't allow mutable access (#17116), so it will never conflict. And it's never valid to access resources through EntityMut::get_components_mut anyway (#20315).

[chescock]

Would it make sense to have the caller call get_state first and pass in the &Self::State here?

They're almost certainly about to call it anyway, and that would let us avoid needing to do the HashMap lookup in components.component_id::<T>() twice. Or even more than twice, since has_conflicts calls this in a loop.

And that would let you handle FilteredEntityMut and EntityMutExcept by including a variant of EcsAccessType with a borrowed &Access. That could eliminate a lot of the complexity around except_index.

It would be a little awkward to hook in to get_components_mut, since get_state is called inside of UnsafeEntityCell::get_components but we want to check the conflicts outside of that. Although even if you wind up calling get_state twice, that's no more calls to component_id::<T>() than you're doing now!

[hymm]

I have no idea what that would look like. How would you convert the get_state to an iterator?

edit: I have an idea of how this might look.

[chescock]

I have no idea what that would look like. How would you convert the get_state to an iterator?

I meant that the State is where we store the ComponentId, so you could do

pub unsafe trait QueryData: WorldQuery {
    fn iter_access(state: &Self::State) -> impl Iterator<Item = EcsAccessType>;
}

unsafe impl<'a, T: Component> QueryData for &'a T {
    fn iter_access(state: &Self::State) -> impl Iterator<Item = EcsAccessType> {
        // Don't need to call `component_id::<T>`!
        iter::once(EcsAccessType::Component(EcsAccessLevel::Read(*state)))
    }
}

// And then call it like
let state = Q::get_state(components)?;
let iter = Q::iter_access(&state).enumerate();

And that structure would also let you handle FilteredEntityMut and EntityMutExcept by borrowing, like

pub enum EcsAccessLevel<'a> {
    Filtered(&'a Access),
    // ...
}

unsafe impl<'a, 'b, B: Bundle> QueryData for EntityMutExcept<'a, 'b, B> {
    fn iter_access<'s>(state: &'s Self::State) -> impl Iterator<Item = EcsAccessType<'s>> {
        iter::once(EcsAccessType::Component(EcsAccessLevel::Filtered(state)))
    }
}

That should be straightforward to handle in EcsAccessType::is_compatible(), and it avoids all the complexity of except_index.

[hymm]

Yeah, good idea. This was a nice bump in perf. More than twice as fast. I updated the perf table above with the new numbers.

[hymm]

Oh wait. get_state allocates in the case of Entity*Except so this won't work.

[chescock]

Note that since adding a component to an entity registers it, ComponentNotRegistered is just a special case of EntityDoesNotMatch. I don't think a caller can ever really do anything differently in those cases, so I'd be inclined to remove the ComponentNotRegistered variant and just return EntityDoesNotMatch in that case.

[hymm]

You can technically call this method before the component has been registered. I hit this while I was writing my tests. Is the average user likely to hit this? probably not. But the way you would fix this is by registering the component which is not what you would do for EntityDoesNotMatch.

[chescock]

You can technically call this method before the component has been registered. I hit this while I was writing my tests. Is the average user likely to hit this? probably not. But the way you would fix this is by registering the component which is not what you would do for EntityDoesNotMatch.

But if the component hasn't been registered, then it hasn't been inserted onto any entity, which means it hasn't been inserted onto the current entity. So registering it will just change the error to EntityDoesNotMatch. And inserting the component onto that entity will fix either error.

... oh, except for Option<D> or Has<C>, which might fail instead of returning None or false. Blah.

[chescock]

Are we sure we don't want to panic on conflicting access? It's based on the static type, so any given call will either always succeed or always fail. And callers will be tempted to ignore the error payload and treat Conflict the same as EntityDoesNotMatch, which would make it harder to notice that the type has a conflict.

[hymm]

yeah, I guess it's a safety issue like with normal systems. Hopefully with enough const rust features we'll be able to move a lot of these checks to compile time. We did get const type id's recently.

With this change I am tempted to change these apis back to being options. As you said above, it's not easy to hit the component not registered error.

[chescock]

We may also want into_components_mut versions of these that consume self and return the full 'w lifetime.

You can share the implementations by implementing EntityMut::get_components_mut as self.reborrow().into_components_mut::<Q>() and EntityWorldMut::get_components_mut as self.as_mutable().into_components_mut::<Q>(). That also makes it harder to accidentally extend the lifetimes, since you're delegating that to the existing reborrow() and as_mutable() methods. (That's what I did in #20273.)

[hymm]

I'm a little curious just how much faster it is than doing a naive check like in #20273.

I didn't do exactly that, but I did try the algorithm in this pr with fixedbitsets and it was significantly slower at 2 and 5 components. iirc it was around 30us for both. Around the same at 10 components and faster at 16.