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

Added missing details to SystemParam Local documentation. (#7106)

Browse Source 
# Objective

`SystemParam` `Local`s documentation currently leaves out information that should be documented.
- What happens when multiple `SystemParam`s within the same system have the same `Local` type.
- What lifetime parameter is expected by `Local`.
 
## Solution

- Added sentences to documentation to communicate this information.
- Renamed `Local` lifetimes in code to `'s` where they previously were not. Users can get complicated incorrect suggested fixes if they pass the wrong lifetime. Some instance of the code had `'w` indicating the expected lifetime might not have been known to those that wrote the code either.

Co-authored-by: iiYese <83026177+iiYese@users.noreply.github.com>
This commit is contained in:
iiYese 2023-01-06 15:40:10 +00:00
parent 3dd8b42f72
commit 653c062ba3
1 changed files with 12 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -798,6 +798,10 @@ unsafe impl SystemParamState for WorldState {
/// ///
/// A local may only be accessed by the system itself and is therefore not visible to other systems. /// A local may only be accessed by the system itself and is therefore not visible to other systems.
/// If two or more systems specify the same local type each will have their own unique local. /// If two or more systems specify the same local type each will have their own unique local.
/// If multiple [`SystemParam`]s within the same system each specify the same local type
/// each will get their own distinct data storage.
///
/// The supplied lifetime parameter is the [`SystemParam`]s `'s` lifetime.
/// ///
/// # Examples /// # Examples
/// ///
@ -837,12 +841,12 @@ unsafe impl SystemParamState for WorldState {
/// // .add_system(reset_to_system(my_config)) /// // .add_system(reset_to_system(my_config))
/// # assert_is_system(reset_to_system(Config(10))); /// # assert_is_system(reset_to_system(Config(10)));
/// ``` /// ```
pub struct Local<'a, T: FromWorld + Send + 'static>(pub(crate) &'a mut T); pub struct Local<'s, T: FromWorld + Send + 'static>(pub(crate) &'s mut T);
// SAFETY: Local only accesses internal state // SAFETY: Local only accesses internal state
unsafe impl<'a, T: FromWorld + Send + 'static> ReadOnlySystemParam for Local<'a, T> {} unsafe impl<'s, T: FromWorld + Send + 'static> ReadOnlySystemParam for Local<'s, T> {}
impl<'a, T: FromWorld + Send + Sync + 'static> Debug for Local<'a, T> impl<'s, T: FromWorld + Send + Sync + 'static> Debug for Local<'s, T>
where where
T: Debug, T: Debug,
{ {
@ -851,7 +855,7 @@ where
} }
} }
impl<'a, T: FromWorld + Send + Sync + 'static> Deref for Local<'a, T> { impl<'s, T: FromWorld + Send + Sync + 'static> Deref for Local<'s, T> {
type Target = T; type Target = T;
#[inline] #[inline]
@ -860,14 +864,14 @@ impl<'a, T: FromWorld + Send + Sync + 'static> Deref for Local<'a, T> {
} }
} }
impl<'a, T: FromWorld + Send + Sync + 'static> DerefMut for Local<'a, T> { impl<'s, T: FromWorld + Send + Sync + 'static> DerefMut for Local<'s, T> {
#[inline] #[inline]
fn deref_mut(&mut self) -> &mut Self::Target { fn deref_mut(&mut self) -> &mut Self::Target {
self.0 self.0
} }
} }
impl<'w, 'a, T: FromWorld + Send + 'static> IntoIterator for &'a Local<'w, T> impl<'s, 'a, T: FromWorld + Send + 'static> IntoIterator for &'a Local<'s, T>
where where
&'a T: IntoIterator, &'a T: IntoIterator,
{ {
@ -879,7 +883,7 @@ where
} }
} }
impl<'w, 'a, T: FromWorld + Send + 'static> IntoIterator for &'a mut Local<'w, T> impl<'s, 'a, T: FromWorld + Send + 'static> IntoIterator for &'a mut Local<'s, T>
where where
&'a mut T: IntoIterator, &'a mut T: IntoIterator,
{ {
@ -895,7 +899,7 @@ where
#[doc(hidden)] #[doc(hidden)]
pub struct LocalState<T: Send + 'static>(pub(crate) SyncCell<T>); pub struct LocalState<T: Send + 'static>(pub(crate) SyncCell<T>);
impl<'a, T: FromWorld + Send + 'static> SystemParam for Local<'a, T> { impl<'s, T: FromWorld + Send + 'static> SystemParam for Local<'s, T> {
type State = LocalState<T>; type State = LocalState<T>;
} }