Skip to content

Commit

Permalink
Revise SystemParam docs (bevyengine#7274)
Browse files Browse the repository at this point in the history
# Objective

Increase clarity in a few places for the `SystemParam` docs.
  • Loading branch information
JoJoJet authored and ItsDoot committed Feb 1, 2023
1 parent caf52c1 commit d77806f
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 5 deletions.
14 changes: 9 additions & 5 deletions crates/bevy_ecs/src/system/system_param.rs
Original file line number Diff line number Diff line change
Expand Up @@ -124,8 +124,11 @@ use std::{
///
/// # Safety
///
/// The implementor must ensure that [`SystemParam::init_state`] correctly registers all
/// [`World`] accesses used by this [`SystemParam`] with the provided [`system_meta`](SystemMeta).
/// The implementor must ensure the following is true.
/// - [`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 {
/// Used to store data which persists across invocations of a system.
type State: Send + Sync + 'static;
Expand Down Expand Up @@ -158,7 +161,9 @@ pub unsafe trait SystemParam: Sized {
/// # Safety
///
/// 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>(
state: &'state mut Self::State,
system_meta: &SystemMeta,
Expand Down Expand Up @@ -589,7 +594,7 @@ unsafe impl<'a, T: Resource> SystemParam for Option<ResMut<'a, T>> {
// SAFETY: Commands only accesses internal state
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<'_, '_> {
type State = CommandQueue;
type Item<'w, 's> = Commands<'w, 's>;
Expand Down Expand Up @@ -1305,7 +1310,6 @@ unsafe impl<'s> ReadOnlySystemParam for SystemName<'s> {}

macro_rules! impl_system_param_tuple {
($($param: ident),*) => {

// SAFETY: tuple consists only of ReadOnlySystemParams
unsafe impl<$($param: ReadOnlySystemParam),*> ReadOnlySystemParam for ($($param,)*) {}

Expand Down
4 changes: 4 additions & 0 deletions crates/bevy_render/src/extract_param.rs
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ pub struct ExtractState<P: SystemParam + 'static> {
unsafe impl<P> ReadOnlySystemParam for Extract<'_, '_, P> where P: ReadOnlySystemParam {}

// 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>
where
P: ReadOnlySystemParam,
Expand All @@ -77,6 +78,9 @@ where
world: &'w World,
change_tick: u32,
) -> 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(
&mut state.main_world_state,
system_meta,
Expand Down

0 comments on commit d77806f

Please sign in to comment.