forestia/bevy
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation for WorldQuery and filters (#11952)

Browse Source 
# Objective

`update_archetype_component_access` was removed from queries in #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.
This commit is contained in:
Kristoffer Søholm 2024-02-18 22:58:26 +01:00 committed by GitHub
parent cb5ff51d1e
commit 6026c08c04
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 8 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
crates/bevy_ecs/src/query/filter.rs
View File

@ -70,8 +70,6 @@ use std::{cell::UnsafeCell, marker::PhantomData};
/// [`matches_component_set`]: Self::matches_component_set /// [`matches_component_set`]: Self::matches_component_set
/// [`Query`]: crate::system::Query /// [`Query`]: crate::system::Query
/// [`State`]: Self::State /// [`State`]: Self::State
/// [`update_archetype_component_access`]: Self::update_archetype_component_access
/// [`update_component_access`]: Self::update_component_access
pub trait QueryFilter: WorldQuery { pub trait QueryFilter: WorldQuery {
/// Returns true if (and only if) this Filter relies strictly on archetypes to limit which /// Returns true if (and only if) this Filter relies strictly on archetypes to limit which
@ -123,7 +121,7 @@ pub trait QueryFilter: WorldQuery {
pub struct With<T>(PhantomData<T>); pub struct With<T>(PhantomData<T>);
/// SAFETY: /// 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. /// This is sound because `fetch` does not access any components.
/// `update_component_access` adds a `With` filter for `T`. /// `update_component_access` adds a `With` filter for `T`.
/// This is sound because `matches_component_set` returns whether the set contains the component. /// This is sound because `matches_component_set` returns whether the set contains the component.
@ -231,7 +229,7 @@ impl<T: Component> QueryFilter for With<T> {
pub struct Without<T>(PhantomData<T>); pub struct Without<T>(PhantomData<T>);
/// SAFETY: /// 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. /// This is sound because `fetch` does not access any components.
/// `update_component_access` adds a `Without` filter for `T`. /// `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. /// This is sound because `matches_component_set` returns whether the set does not contain the component.
@ -366,7 +364,7 @@ macro_rules! impl_query_filter_tuple {
#[allow(clippy::unused_unit)] #[allow(clippy::unused_unit)]
/// SAFETY: /// SAFETY:
/// `fetch` accesses are a subset of the subqueries' accesses /// `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. /// `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. /// 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,)*)> { unsafe impl<$($filter: QueryFilter),*> WorldQuery for Or<($($filter,)*)> {
@ -579,7 +577,7 @@ pub struct AddedFetch<'w> {
/// SAFETY: /// SAFETY:
/// `fetch` accesses a single component in a readonly way. /// `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. /// `update_component_access` adds a `With` filter for a component.
/// This is sound because `matches_component_set` returns whether the set contains that component. /// This is sound because `matches_component_set` returns whether the set contains that component.
unsafe impl<T: Component> WorldQuery for Added<T> { unsafe impl<T: Component> WorldQuery for Added<T> {
@ -779,7 +777,7 @@ pub struct ChangedFetch<'w> {
/// SAFETY: /// SAFETY:
/// `fetch` accesses a single component in a readonly way. /// `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. /// `update_component_access` adds a `With` filter for a component.
/// This is sound because `matches_component_set` returns whether the set contains that component. /// This is sound because `matches_component_set` returns whether the set contains that component.
unsafe impl<T: Component> WorldQuery for Changed<T> { unsafe impl<T: Component> WorldQuery for Changed<T> {

6
crates/bevy_ecs/src/query/world_query.rs
View File

@ -57,7 +57,6 @@ pub unsafe trait WorldQuery {
/// ///
/// # Safety /// # 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 /// - `state` must have been initialized (via [`WorldQuery::init_state`]) using the same `world` passed
/// in to this function. /// in to this function.
unsafe fn init_fetch<'w>( unsafe fn init_fetch<'w>(
@ -128,7 +127,8 @@ pub unsafe trait WorldQuery {
/// Creates and initializes a [`State`](WorldQuery::State) for this [`WorldQuery`] type. /// Creates and initializes a [`State`](WorldQuery::State) for this [`WorldQuery`] type.
fn init_state(world: &mut World) -> Self::State; 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>; fn get_state(world: &World) -> Option<Self::State>;
/// Returns `true` if this query matches a set of components. Otherwise, returns `false`. /// Returns `true` if this query matches a set of components. Otherwise, returns `false`.
@ -145,7 +145,7 @@ macro_rules! impl_tuple_world_query {
#[allow(clippy::unused_unit)] #[allow(clippy::unused_unit)]
/// SAFETY: /// SAFETY:
/// `fetch` accesses are the conjunction of the subqueries' accesses /// `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. /// `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`. /// This is sound because `matches_component_set` always returns `false` if any the subqueries' implementations return `false`.
unsafe impl<$($name: WorldQuery),*> WorldQuery for ($($name,)*) { unsafe impl<$($name: WorldQuery),*> WorldQuery for ($($name,)*) {