Skip to content

Commit

Permalink
Update documentation for WorldQuery and filters (bevyengine#11952)
Browse files Browse the repository at this point in the history
# Objective

`update_archetype_component_access` was removed from queries in bevyengine#9774,
but some documentation still refers to it.

## Solution

Update the documentation. Since a bunch of these were in SAFETY comments
it would be nice if someone who knows the details better could check
that the rest of those comments are still valid.
  • Loading branch information
kristoff3r authored and msvbg committed Feb 26, 2024
1 parent f24cc41 commit ad95ea7
Show file tree
Hide file tree
Showing 2 changed files with 8 additions and 10 deletions.
12 changes: 5 additions & 7 deletions crates/bevy_ecs/src/query/filter.rs
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,6 @@ use std::{cell::UnsafeCell, marker::PhantomData};
/// [`matches_component_set`]: Self::matches_component_set
/// [`Query`]: crate::system::Query
/// [`State`]: Self::State
/// [`update_archetype_component_access`]: Self::update_archetype_component_access
/// [`update_component_access`]: Self::update_component_access

pub trait QueryFilter: WorldQuery {
/// Returns true if (and only if) this Filter relies strictly on archetypes to limit which
Expand Down Expand Up @@ -123,7 +121,7 @@ pub trait QueryFilter: WorldQuery {
pub struct With<T>(PhantomData<T>);

/// SAFETY:
/// `update_component_access` and `update_archetype_component_access` do not add any accesses.
/// `update_component_access` does not add any accesses.
/// This is sound because `fetch` does not access any components.
/// `update_component_access` adds a `With` filter for `T`.
/// This is sound because `matches_component_set` returns whether the set contains the component.
Expand Down Expand Up @@ -231,7 +229,7 @@ impl<T: Component> QueryFilter for With<T> {
pub struct Without<T>(PhantomData<T>);

/// SAFETY:
/// `update_component_access` and `update_archetype_component_access` do not add any accesses.
/// `update_component_access` does not add any accesses.
/// This is sound because `fetch` does not access any components.
/// `update_component_access` adds a `Without` filter for `T`.
/// This is sound because `matches_component_set` returns whether the set does not contain the component.
Expand Down Expand Up @@ -366,7 +364,7 @@ macro_rules! impl_query_filter_tuple {
#[allow(clippy::unused_unit)]
/// SAFETY:
/// `fetch` accesses are a subset of the subqueries' accesses
/// This is sound because `update_component_access` and `update_archetype_component_access` adds accesses according to the implementations of all the subqueries.
/// This is sound because `update_component_access` adds accesses according to the implementations of all the subqueries.
/// `update_component_access` replace the filters with a disjunction where every element is a conjunction of the previous filters and the filters of one of the subqueries.
/// This is sound because `matches_component_set` returns a disjunction of the results of the subqueries' implementations.
unsafe impl<$($filter: QueryFilter),*> WorldQuery for Or<($($filter,)*)> {
Expand Down Expand Up @@ -579,7 +577,7 @@ pub struct AddedFetch<'w> {

/// SAFETY:
/// `fetch` accesses a single component in a readonly way.
/// This is sound because `update_component_access` and `update_archetype_component_access` add read access for that component and panic when appropriate.
/// This is sound because `update_component_access` adds read access for that component and panics when appropriate.
/// `update_component_access` adds a `With` filter for a component.
/// This is sound because `matches_component_set` returns whether the set contains that component.
unsafe impl<T: Component> WorldQuery for Added<T> {
Expand Down Expand Up @@ -779,7 +777,7 @@ pub struct ChangedFetch<'w> {

/// SAFETY:
/// `fetch` accesses a single component in a readonly way.
/// This is sound because `update_component_access` and `update_archetype_component_access` add read access for that component and panic when appropriate.
/// This is sound because `update_component_access` add read access for that component and panics when appropriate.
/// `update_component_access` adds a `With` filter for a component.
/// This is sound because `matches_component_set` returns whether the set contains that component.
unsafe impl<T: Component> WorldQuery for Changed<T> {
Expand Down
6 changes: 3 additions & 3 deletions crates/bevy_ecs/src/query/world_query.rs
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,6 @@ pub unsafe trait WorldQuery {
///
/// # Safety
///
/// - `world` must have permission to access any of the components specified in `Self::update_archetype_component_access`.
/// - `state` must have been initialized (via [`WorldQuery::init_state`]) using the same `world` passed
/// in to this function.
unsafe fn init_fetch<'w>(
Expand Down Expand Up @@ -128,7 +127,8 @@ pub unsafe trait WorldQuery {
/// Creates and initializes a [`State`](WorldQuery::State) for this [`WorldQuery`] type.
fn init_state(world: &mut World) -> Self::State;

/// Attempts to initializes a [`State`](WorldQuery::State) for this [`WorldQuery`] type.
/// Attempts to initialize a [`State`](WorldQuery::State) for this [`WorldQuery`] type using read-only
/// access to the [`World`].
fn get_state(world: &World) -> Option<Self::State>;

/// Returns `true` if this query matches a set of components. Otherwise, returns `false`.
Expand All @@ -145,7 +145,7 @@ macro_rules! impl_tuple_world_query {
#[allow(clippy::unused_unit)]
/// SAFETY:
/// `fetch` accesses are the conjunction of the subqueries' accesses
/// This is sound because `update_component_access` and `update_archetype_component_access` adds accesses according to the implementations of all the subqueries.
/// This is sound because `update_component_access` adds accesses according to the implementations of all the subqueries.
/// `update_component_access` adds all `With` and `Without` filters from the subqueries.
/// This is sound because `matches_component_set` always returns `false` if any the subqueries' implementations return `false`.
unsafe impl<$($name: WorldQuery),*> WorldQuery for ($($name,)*) {
Expand Down

0 comments on commit ad95ea7

Please sign in to comment.