From bbb54020d9d6b09e1554678b7edf2d3804d975d6 Mon Sep 17 00:00:00 2001 From: james7132 Date: Sun, 10 Mar 2024 01:02:00 -0800 Subject: [PATCH 1/3] Mention in docs about the query iteration order and result uniquness. --- crates/bevy_ecs/src/system/query.rs | 41 ++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 4 deletions(-) diff --git a/crates/bevy_ecs/src/system/query.rs b/crates/bevy_ecs/src/system/query.rs index 773a0c0e3aff4..db34e2513e0ea 100644 --- a/crates/bevy_ecs/src/system/query.rs +++ b/crates/bevy_ecs/src/system/query.rs @@ -407,6 +407,9 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// Returns an [`Iterator`] over the read-only query items. /// + /// This iterator is always guaranteed to return results from each matching entity once and only once. + /// Iteration order is not guaranteed. + /// /// # Example /// /// Here, the `report_names_system` iterates over the `Player` component of every entity that contains it: @@ -442,6 +445,9 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// Returns an [`Iterator`] over the query items. /// + /// This iterator is always guaranteed to return results from each matching entity once and only once. + /// Iteration order is not guaranteed. + /// /// # Example /// /// Here, the `gravity_system` updates the `Velocity` component of every entity that contains it: @@ -474,6 +480,9 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// Returns a [`QueryCombinationIter`] over all combinations of `K` read-only query items without repetition. /// + /// This iterator is always guaranteed to return results from each unique pair of matching entities. + /// Iteration order is not guaranteed. + /// /// # Example /// /// ``` @@ -509,6 +518,9 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// Returns a [`QueryCombinationIter`] over all combinations of `K` query items without repetition. /// + /// This iterator is always guaranteed to return results from each unique pair of matching entities. + /// Iteration order is not guaranteed. + /// /// # Example /// /// ``` @@ -539,8 +551,8 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// Returns an [`Iterator`] over the read-only query items generated from an [`Entity`] list. /// - /// Items are returned in the order of the list of entities. - /// Entities that don't match the query are skipped. + /// Items are returned in the order of the list of entities, and may not be unique if the input + /// doesnn't guarantee uniqueness. Entities that don't match the query are skipped. /// /// # Example /// @@ -596,8 +608,8 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// Returns an iterator over the query items generated from an [`Entity`] list. /// - /// Items are returned in the order of the list of entities. - /// Entities that don't match the query are skipped. + /// Items are returned in the order of the list of entities, and may not be unique if the input + /// doesnn't guarantee uniqueness. Entities that don't match the query are skipped. /// /// # Examples /// @@ -648,6 +660,9 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// Returns an [`Iterator`] over the query items. /// + /// This iterator is always guaranteed to return results from each matching entity once and only once. + /// Iteration order is not guaranteed. + /// /// # Safety /// /// This function makes it possible to violate Rust's aliasing guarantees. @@ -669,6 +684,9 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// Iterates over all possible combinations of `K` query items without repetition. /// + /// This iterator is always guaranteed to return results from each unique pair of matching entities. + /// Iteration order is not guaranteed. + /// /// # Safety /// /// This allows aliased mutability. @@ -692,6 +710,9 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// Returns an [`Iterator`] over the query items generated from an [`Entity`] list. /// + /// Items are returned in the order of the list of entities, and may not be unique if the input + /// doesnn't guarantee uniqueness. Entities that don't match the query are skipped. + /// /// # Safety /// /// This allows aliased mutability and does not check for entity uniqueness. @@ -723,6 +744,12 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// Returns a parallel iterator over the query results for the given [`World`]. /// + /// This parallel iterator is always guaranteed to return results from each matching entity once and + /// only once. Iteration order and thread assignment is not guaranteed. + /// + /// If the `multithreaded` feature is disabled, iterating with this operates identically to [`Iterator::for_each`] + /// on [`QueryIter`]. + /// /// This can only be called for read-only queries, see [`par_iter_mut`] for write-queries. /// /// Note that you must use the `for_each` method to iterate over the @@ -743,6 +770,12 @@ impl<'w, 's, D: QueryData, F: QueryFilter> Query<'w, 's, D, F> { /// Returns a parallel iterator over the query results for the given [`World`]. /// + /// This parallel iterator is always guaranteed to return results from each matching entity once and + /// only once. Iteration order and thread assignment is not guaranteed. + /// + /// If the `multithreaded` feature is disabled, iterating with this operates identically to [`Iterator::for_each`] + /// on [`QueryIter`]. + /// /// This can only be called for mutable queries, see [`par_iter`] for read-only-queries. /// /// # Example From 8336fccee000cf0f361592940b1e282b530fc4e2 Mon Sep 17 00:00:00 2001 From: james7132 Date: Sun, 10 Mar 2024 01:15:45 -0800 Subject: [PATCH 2/3] Add the same mentions to QueryState --- crates/bevy_ecs/src/query/state.rs | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/crates/bevy_ecs/src/query/state.rs b/crates/bevy_ecs/src/query/state.rs index 3eb76d3d3df75..7ac0a866d2e56 100644 --- a/crates/bevy_ecs/src/query/state.rs +++ b/crates/bevy_ecs/src/query/state.rs @@ -730,6 +730,9 @@ impl QueryState { } /// Returns an [`Iterator`] over the query results for the given [`World`]. + /// + /// This iterator is always guaranteed to return results from each matching entity once and only once. + /// Iteration order is not guaranteed. #[inline] pub fn iter_mut<'w, 's>(&'s mut self, world: &'w mut World) -> QueryIter<'w, 's, D, F> { self.update_archetypes(world); @@ -744,6 +747,9 @@ impl QueryState { /// Returns an [`Iterator`] over the query results for the given [`World`] without updating the query's archetypes. /// Archetypes must be manually updated before by using [`Self::update_archetypes`]. /// + /// This iterator is always guaranteed to return results from each matching entity once and only once. + /// Iteration order is not guaranteed. + /// /// This can only be called for read-only queries. #[inline] pub fn iter_manual<'w, 's>(&'s self, world: &'w World) -> QueryIter<'w, 's, D::ReadOnly, F> { @@ -776,6 +782,9 @@ impl QueryState { /// - if `K > N`: empty set (no `K`-sized combinations exist) /// /// The `iter_combinations` method does not guarantee order of iteration. + /// + /// This iterator is always guaranteed to return results from each unique pair of matching entities. + /// Iteration order is not guaranteed. /// /// This can only be called for read-only queries, see [`Self::iter_combinations_mut`] for /// write-queries. @@ -923,6 +932,9 @@ impl QueryState { /// Returns an [`Iterator`] over the query results for the given [`World`]. /// + /// This iterator is always guaranteed to return results from each matching entity once and only once. + /// Iteration order is not guaranteed. + /// /// # Safety /// /// This does not check for mutable query correctness. To be safe, make sure mutable queries @@ -940,6 +952,9 @@ impl QueryState { /// given [`World`] without repetition. /// This can only be called for read-only queries. /// + /// This iterator is always guaranteed to return results from each unique pair of matching entities. + /// Iteration order is not guaranteed. + /// /// # Safety /// /// This does not check for mutable query correctness. To be safe, make sure mutable queries @@ -960,6 +975,9 @@ impl QueryState { /// Returns an [`Iterator`] for the given [`World`], where the last change and /// the current change tick are given. /// + /// This iterator is always guaranteed to return results from each matching entity once and only once. + /// Iteration order is not guaranteed. + /// /// # Safety /// /// This does not check for mutable query correctness. To be safe, make sure mutable queries @@ -979,6 +997,9 @@ impl QueryState { /// Returns an [`Iterator`] for the given [`World`] and list of [`Entity`]'s, where the last change and /// the current change tick are given. /// + /// This iterator is always guaranteed to return results from each unique pair of matching entities. + /// Iteration order is not guaranteed. + /// /// # Safety /// /// This does not check for mutable query correctness. To be safe, make sure mutable queries @@ -1004,6 +1025,9 @@ impl QueryState { /// given [`World`] without repetition. /// This can only be called for read-only queries. /// + /// This iterator is always guaranteed to return results from each unique pair of matching entities. + /// Iteration order is not guaranteed. + /// /// # Safety /// /// This does not check for mutable query correctness. To be safe, make sure mutable queries From 5a9d70605a3b37e5aa8b0cad079f38e78f201045 Mon Sep 17 00:00:00 2001 From: james7132 Date: Sun, 10 Mar 2024 01:27:20 -0800 Subject: [PATCH 3/3] Formatting --- crates/bevy_ecs/src/query/state.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/bevy_ecs/src/query/state.rs b/crates/bevy_ecs/src/query/state.rs index 7ac0a866d2e56..8abd77d00d091 100644 --- a/crates/bevy_ecs/src/query/state.rs +++ b/crates/bevy_ecs/src/query/state.rs @@ -782,7 +782,7 @@ impl QueryState { /// - if `K > N`: empty set (no `K`-sized combinations exist) /// /// The `iter_combinations` method does not guarantee order of iteration. - /// + /// /// This iterator is always guaranteed to return results from each unique pair of matching entities. /// Iteration order is not guaranteed. ///