add docs explaining the two accesses of a System meta (#14580)

# Objective

When reading the ECS code it is sometimes confusing to understand why we
have 2 accesses, one of ComponentId and one of ArchetypeComponentId


## Solution

Make the usage of these 2 accesses more explicit

---------

Co-authored-by: Pascal Hertleif <killercup@gmail.com>
This commit is contained in:
Periwink 2024-08-19 17:32:45 -04:00 committed by GitHub
parent 6d3b2faf8a
commit eaa805102d
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -20,7 +20,19 @@ use super::{In, IntoSystem, ReadOnlySystem, SystemParamBuilder};
#[derive(Clone)]
pub struct SystemMeta {
pub(crate) name: Cow<'static, str>,
/// The set of component accesses for this system. This is used to determine
/// - soundness issues (e.g. multiple [`SystemParam`]s mutably accessing the same component)
/// - ambiguities in the schedule (e.g. two systems that have some sort of conflicting access)
pub(crate) component_access_set: FilteredAccessSet<ComponentId>,
/// This [`Access`] is used to determine which systems can run in parallel with each other
/// in the multithreaded executor.
///
/// We use a [`ArchetypeComponentId`] as it is more precise than just checking [`ComponentId`]:
/// for example if you have one system with `Query<&mut T, With<A>>` and one system with `Query<&mut T, With<B>>`
/// they conflict if you just look at the [`ComponentId`] of `T`; but if there are no archetypes with
/// both `A`, `B` and `T` then in practice there's no risk of conflict. By using [`ArchetypeComponentId`]
/// we can be more precise because we can check if the existing archetypes of the [`World`]
/// cause a conflict
pub(crate) archetype_component_access: Access<ArchetypeComponentId>,
// NOTE: this must be kept private. making a SystemMeta non-send is irreversible to prevent
// SystemParams from overriding each other