Skip to content

Commit ebbd961

Browse files
docs: enhance documentation in query.rs to clarify borrowing rules (#17370)
docs: enhance documentation in `query.rs` to clarify borrowing rules. Please, let me know if you don't agree with the wording.. There is always room for improvement. Tested locally and it looks like this: ![image](https://github.com/user-attachments/assets/1283fcac-c5f7-426f-844f-fc2a12ce2b42) --------- Co-authored-by: Alice Cecile <[email protected]>
1 parent 15facbb commit ebbd961

File tree

1 file changed

+12
-0
lines changed

1 file changed

+12
-0
lines changed

crates/bevy_ecs/src/system/query.rs

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -227,6 +227,11 @@ use core::{
227227
/// # struct ComponentA;
228228
/// # fn system(
229229
/// // This will panic!
230+
/// // EntityRef provides read access to ALL components on an entity.
231+
/// // When combined with &mut ComponentA in the same query, it creates
232+
/// // a conflict because EntityRef could read ComponentA while the &mut
233+
/// // attempts to modify it - violating Rust's borrowing rules of no
234+
/// // simultaneous read+write access.
230235
/// query: Query<(EntityRef, &mut ComponentA)>
231236
/// # ) {}
232237
/// # bevy_ecs::system::assert_system_does_not_conflict(system);
@@ -239,11 +244,18 @@ use core::{
239244
/// # struct ComponentB;
240245
/// # fn system(
241246
/// // This will not panic.
247+
/// // This creates a perfect separation where:
248+
/// // 1. First query reads entities that have ComponentA
249+
/// // 2. Second query modifies ComponentB only on entities that DON'T have ComponentA
250+
/// // Result: No entity can ever be accessed by both queries simultaneously
242251
/// query_a: Query<EntityRef, With<ComponentA>>,
243252
/// query_b: Query<&mut ComponentB, Without<ComponentA>>,
244253
/// # ) {}
245254
/// # bevy_ecs::system::assert_system_does_not_conflict(system);
246255
/// ```
256+
/// The fundamental rule: [`EntityRef`]'s ability to read all components means it can never
257+
/// coexist with mutable access. With/Without filters guarantee this by keeping the
258+
/// queries on completely separate entities.
247259
///
248260
/// # Accessing query items
249261
///

0 commit comments

Comments
 (0)