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

Revise SystemParam docs (#7274)

Browse Source 
# Objective

Increase clarity in a few places for the `SystemParam` docs.
This commit is contained in:
JoJoJet 2023-01-20 13:39:23 +00:00
parent f024bce2b8
commit 5d5a504685
2 changed files with 13 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
crates/bevy_ecs/src/system/system_param.rs
View File

@ -124,8 +124,11 @@ use std::{
/// ///
/// # Safety /// # Safety
/// ///
/// The implementor must ensure that [`SystemParam::init_state`] correctly registers all /// The implementor must ensure the following is true.
/// [`World`] accesses used by this [`SystemParam`] with the provided [`system_meta`](SystemMeta). /// - [`SystemParam::init_state`] correctly registers all [`World`] accesses used
/// by [`SystemParam::get_param`] with the provided [`system_meta`](SystemMeta).
/// - None of the world accesses may conflict with any prior accesses registered
/// on `system_meta`.
pub unsafe trait SystemParam: Sized { pub unsafe trait SystemParam: Sized {
/// Used to store data which persists across invocations of a system. /// Used to store data which persists across invocations of a system.
type State: Send + Sync + 'static; type State: Send + Sync + 'static;
@ -158,7 +161,9 @@ pub unsafe trait SystemParam: Sized {
/// # Safety /// # Safety
/// ///
/// This call might use any of the [`World`] accesses that were registered in [`Self::init_state`]. /// This call might use any of the [`World`] accesses that were registered in [`Self::init_state`].
/// You must ensure that none of those accesses conflict with any other [`SystemParam`]s running in parallel with this one. /// - None of those accesses may conflict with any other [`SystemParam`]s
/// that exist at the same time, including those on other threads.
/// - `world` must be the same `World` that was used to initialize [`state`](SystemParam::init_state).
unsafe fn get_param<'world, 'state>( unsafe fn get_param<'world, 'state>(
state: &'state mut Self::State, state: &'state mut Self::State,
system_meta: &SystemMeta, system_meta: &SystemMeta,
@ -589,7 +594,7 @@ unsafe impl<'a, T: Resource> SystemParam for Option<ResMut<'a, T>> {
// SAFETY: Commands only accesses internal state // SAFETY: Commands only accesses internal state
unsafe impl<'w, 's> ReadOnlySystemParam for Commands<'w, 's> {} unsafe impl<'w, 's> ReadOnlySystemParam for Commands<'w, 's> {}
// SAFETY: only local state is accessed // SAFETY: `Commands::get_param` does not access the world.
unsafe impl SystemParam for Commands<'_, '_> { unsafe impl SystemParam for Commands<'_, '_> {
type State = CommandQueue; type State = CommandQueue;
type Item<'w, 's> = Commands<'w, 's>; type Item<'w, 's> = Commands<'w, 's>;
@ -1305,7 +1310,6 @@ unsafe impl<'s> ReadOnlySystemParam for SystemName<'s> {}
macro_rules! impl_system_param_tuple { macro_rules! impl_system_param_tuple {
($($param: ident),*) => { ($($param: ident),*) => {
// SAFETY: tuple consists only of ReadOnlySystemParams // SAFETY: tuple consists only of ReadOnlySystemParams
unsafe impl<$($param: ReadOnlySystemParam),*> ReadOnlySystemParam for ($($param,)*) {} unsafe impl<$($param: ReadOnlySystemParam),*> ReadOnlySystemParam for ($($param,)*) {}

4
crates/bevy_render/src/extract_param.rs
View File

@ -56,6 +56,7 @@ pub struct ExtractState<P: SystemParam + 'static> {
unsafe impl<P> ReadOnlySystemParam for Extract<'_, '_, P> where P: ReadOnlySystemParam {} unsafe impl<P> ReadOnlySystemParam for Extract<'_, '_, P> where P: ReadOnlySystemParam {}
// SAFETY: The only `World` access is properly registered by `Res<MainWorld>::init_state`. // SAFETY: The only `World` access is properly registered by `Res<MainWorld>::init_state`.
// This call will also ensure that there are no conflicts with prior params.
unsafe impl<P> SystemParam for Extract<'_, '_, P> unsafe impl<P> SystemParam for Extract<'_, '_, P>
where where
P: ReadOnlySystemParam, P: ReadOnlySystemParam,
@ -77,6 +78,9 @@ where
world: &'w World, world: &'w World,
change_tick: u32, change_tick: u32,
) -> Self::Item<'w, 's> { ) -> Self::Item<'w, 's> {
// SAFETY:
// - The caller ensures that `world` is the same one that `init_state` was called with.
// - The caller ensures that no other `SystemParam`s will conflict with the accesses we have registered.
let main_world = Res::<MainWorld>::get_param( let main_world = Res::<MainWorld>::get_param(
&mut state.main_world_state, &mut state.main_world_state,
system_meta, system_meta,