get_components_mut (#21780)

# 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    | 1123 us  | 2.2x     |
| 5           | 903 us    | 2902us  | 3.2x     |
| 10          | 1700 us   | 11424 us | 6.72x    |

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

---

## ToDo

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

---------

Co-authored-by: Alice Cecile <[email protected]>

Author: hymm

benches/Cargo.toml

@@ -11,6 +11,7 @@ autobenches = false
 # The primary crate that runs and analyzes our benchmarks. This is a regular dependency because the
 # `bench!` macro refers to it in its documentation.
 criterion = { version = "0.8.0", features = ["html_reports"] }
+seq-macro = "0.3.6"
 
 [dev-dependencies]
 # Bevy crates

benches/benches/bevy_ecs/world/mod.rs

@@ -35,5 +35,8 @@ criterion_group!(
     query_get_many::<2>,
     query_get_many::<5>,
     query_get_many::<10>,
+    query_get_components_mut_2,
+    query_get_components_mut_5,
+    query_get_components_mut_10,
     entity_set_build_and_lookup,
 );

benches/benches/bevy_ecs/world/world_get.rs

@@ -1,15 +1,17 @@
+use benches::bench;
 use core::hint::black_box;
 
 use bevy_ecs::{
     bundle::{Bundle, NoBundleEffect},
     component::Component,
     entity::Entity,
     system::{Query, SystemState},
-    world::World,
+    world::{EntityMut, World},
 };
 use criterion::Criterion;
 use rand::{prelude::SliceRandom, SeedableRng};
 use rand_chacha::ChaCha8Rng;
+use seq_macro::seq;
 
 #[derive(Component, Default)]
 #[component(storage = "Table")]
@@ -357,3 +359,64 @@ pub fn query_get_many<const N: usize>(criterion: &mut Criterion) {
         });
     }
 }
+
+macro_rules! query_get_components_mut {
+    ($function_name:ident, $val:literal) => {
+        pub fn $function_name(criterion: &mut Criterion) {
+            let mut group = criterion.benchmark_group(bench!("world_query_get_components_mut"));
+            group.warm_up_time(core::time::Duration::from_millis(500));
+            group.measurement_time(core::time::Duration::from_secs(4));
+
+            for entity_count in RANGE.map(|i| i * 10_000) {
+                seq!(N in 0..$val {
+                    let (mut world, entities) = setup_wide::<(
+                        #(WideTable<N>,)*
+                    )>(entity_count);
+                });
+                let mut query = world.query::<EntityMut>();
+                group.bench_function(format!("{}_components_{entity_count}_entities", $val), |bencher| {
+                    bencher.iter(|| {
+                        for entity in &entities {
+                            seq!(N in 0..$val {
+                                assert!(query
+                                    .get_mut(&mut world, *entity)
+                                    .unwrap()
+                                    .get_components_mut::<(
+                                            #(&mut WideTable<N>,)*
+                                        )>()
+                                        .is_ok());
+                            });
+                        }
+                    });
+                });
+                group.bench_function(
+                    format!("unchecked_{}_components_{entity_count}_entities", $val),
+                    |bencher| {
+                        bencher.iter(|| {
+                            for entity in &entities {
+                                // SAFETY: no duplicate components are listed
+                                unsafe {
+                                    seq!(N in 0..$val {
+                                        assert!(query
+                                            .get_mut(&mut world, *entity)
+                                            .unwrap()
+                                            .get_components_mut_unchecked::<(
+                                                    #(&mut WideTable<N>,)*
+                                                )>()
+                                                .is_ok());
+                                    });
+                                }
+                            }
+                        });
+                    },
+                );
+            }
+
+            group.finish();
+        }
+    };
+}
+
+query_get_components_mut!(query_get_components_mut_2, 2);
+query_get_components_mut!(query_get_components_mut_5, 5);
+query_get_components_mut!(query_get_components_mut_10, 10);

crates/bevy_ecs/macros/src/query_data.rs

@@ -267,6 +267,12 @@ pub fn derive_query_data_impl(input: TokenStream) -> TokenStream {
                             #(#field_members: <#read_only_field_types>::fetch(&_state.#field_aliases, &mut _fetch.#field_aliases, _entity, _table_row)?,)*
                         })
                     }
+
+                    fn iter_access(
+                        _state: &Self::State,
+                    ) -> impl core::iter::Iterator<Item = #path::query::EcsAccessType<'_>> {
+                        core::iter::empty() #(.chain(<#field_types>::iter_access(&_state.#field_aliases)))*
+                    }
                 }
 
                 impl #user_impl_generics #path::query::ReleaseStateQueryData
@@ -332,6 +338,12 @@ pub fn derive_query_data_impl(input: TokenStream) -> TokenStream {
                         #(#field_members: <#field_types>::fetch(&_state.#field_aliases, &mut _fetch.#field_aliases, _entity, _table_row)?,)*
                     })
                 }
+
+                fn iter_access(
+                    _state: &Self::State,
+                ) -> impl core::iter::Iterator<Item = #path::query::EcsAccessType<'_>> {
+                    core::iter::empty() #(.chain(<#field_types>::iter_access(&_state.#field_aliases)))*
+                }
             }
 
             impl #user_impl_generics #path::query::ReleaseStateQueryData

crates/bevy_ecs/src/event/trigger.rs

@@ -301,7 +301,7 @@ unsafe impl<
                 return;
             }
             if let Ok(entity) = world.get_entity(current_entity)
-                && let Some(item) = entity.get_components::<T>()
+                && let Ok(item) = entity.get_components::<T>()
                 && let Some(traverse_to) = T::traverse(item, event)
             {
                 current_entity = traverse_to;