diff --git a/crates/bevy_ecs/src/world/interior_mutable_world.rs b/crates/bevy_ecs/src/world/interior_mutable_world.rs index 442931652fb4df..eff75ab7ce0e95 100644 --- a/crates/bevy_ecs/src/world/interior_mutable_world.rs +++ b/crates/bevy_ecs/src/world/interior_mutable_world.rs @@ -96,6 +96,11 @@ impl<'w> InteriorMutableWorld<'w> { } /// Gets a reference to the resource of the given type if it exists + /// + /// # Safety + /// All [`InteriorMutableWorld`] methods take `&self` and thus do not check that there is only one unique reference or multiple shared ones. + /// It is the callers responsibility to make sure that there will never be a mutable reference to a value that has other references pointing to it, + /// and that no arbitrary safe code can access a `&World` while some value is mutably borrowed. #[inline] pub unsafe fn get_resource(&self) -> Option<&'w R> { self.0.get_resource::() @@ -107,12 +112,22 @@ impl<'w> InteriorMutableWorld<'w> { /// /// **You should prefer to use the typed API [`InteriorMutableWorld::get_resource`] where possible and only /// use this in cases where the actual types are not known at compile time.** + /// + /// # Safety + /// All [`InteriorMutableWorld`] methods take `&self` and thus do not check that there is only one unique reference or multiple shared ones. + /// It is the callers responsibility to make sure that there will never be a mutable reference to a value that has other references pointing to it, + /// and that no arbitrary safe code can access a `&World` while some value is mutably borrowed. #[inline] pub unsafe fn get_resource_by_id(&self, component_id: ComponentId) -> Option> { self.0.get_resource_by_id(component_id) } /// Gets a mutable reference to the resource of the given type if it exists + /// + /// # Safety + /// All [`InteriorMutableWorld`] methods take `&self` and thus do not check that there is only one unique reference or multiple shared ones. + /// It is the callers responsibility to make sure that there will never be a mutable reference to a value that has other references pointing to it, + /// and that no arbitrary safe code can access a `&World` while some value is mutably borrowed. #[inline] pub unsafe fn get_resource_mut(&self) -> Option> { let component_id = self.0.components.get_resource_id(TypeId::of::())?; @@ -125,6 +140,11 @@ impl<'w> InteriorMutableWorld<'w> { /// /// **You should prefer to use the typed API [`InteriorMutableWorld::get_resource_mut`] where possible and only /// use this in cases where the actual types are not known at compile time.** + /// + /// # Safety + /// All [`InteriorMutableWorld`] methods take `&self` and thus do not check that there is only one unique reference or multiple shared ones. + /// It is the callers responsibility to make sure that there will never be a mutable reference to a value that has other references pointing to it, + /// and that no arbitrary safe code can access a `&World` while some value is mutably borrowed. #[inline] pub unsafe fn get_resource_mut_by_id( &self, @@ -156,6 +176,11 @@ impl<'w> InteriorMutableWorld<'w> { /// Gets a reference to the non-send resource of the given type, if it exists. /// Otherwise returns [None] + /// + /// # Safety + /// All [`InteriorMutableWorld`] methods take `&self` and thus do not check that there is only one unique reference or multiple shared ones. + /// It is the callers responsibility to make sure that there will never be a mutable reference to a value that has other references pointing to it, + /// and that no arbitrary safe code can access a `&World` while some value is mutably borrowed. #[inline] pub unsafe fn get_non_send_resource(&self) -> Option<&R> { self.0.get_non_send_resource::() @@ -175,6 +200,10 @@ impl<'w> InteriorMutableWorld<'w> { /// - `component_id` must be assigned to a component of type `R` /// - Caller must ensure this doesn't violate Rust mutability rules for the given resource. /// - resource is either Send+Sync or the main thread is validated + /// + /// All [`InteriorMutableWorld`] methods take `&self` and thus do not check that there is only one unique reference or multiple shared ones. + /// It is the callers responsibility to make sure that there will never be a mutable reference to a value that has other references pointing to it, + /// and that no arbitrary safe code can access a `&World` while some value is mutably borrowed. #[inline] pub(crate) unsafe fn get_resource_mut_with_id( &self, @@ -196,6 +225,10 @@ impl<'w> InteriorMutableWorld<'w> { /// # Safety /// - `component_id` must be assigned to a component of type `R`. /// - Caller must ensure this doesn't violate Rust mutability rules for the given resource. + /// + /// All [`InteriorMutableWorld`] methods take `&self` and thus do not check that there is only one unique reference or multiple shared ones. + /// It is the callers responsibility to make sure that there will never be a mutable reference to a value that has other references pointing to it, + /// and that no arbitrary safe code can access a `&World` while some value is mutably borrowed. #[inline] pub(crate) unsafe fn get_non_send_mut_with_id( &self, @@ -252,6 +285,10 @@ impl<'w> InteriorMutableEntityRef<'w> { entity_ref::contains_component_with_type(self.world.0, type_id, self.location) } + /// # Safety + /// All [`InteriorMutableEntityRef`] methods take `&self` and thus do not check that there is only one unique reference or multiple shared ones. + /// It is the callers responsibility to make sure that there will never be a mutable reference to a value that has other references pointing to it, + /// and that no arbitrary safe code can access a `&World` while some value is mutably borrowed. #[inline] pub unsafe fn get(&self) -> Option<&'w T> { // SAFETY: @@ -276,6 +313,11 @@ impl<'w> InteriorMutableEntityRef<'w> { /// Retrieves the change ticks for the given component. This can be useful for implementing change /// detection in custom runtimes. + /// + /// # Safety + /// All [`InteriorMutableEntityRef`] methods take `&self` and thus do not check that there is only one unique reference or multiple shared ones. + /// It is the callers responsibility to make sure that there will never be a mutable reference to a value that has other references pointing to it, + /// and that no arbitrary safe code can access a `&World` while some value is mutably borrowed. #[inline] pub unsafe fn get_change_ticks(&self) -> Option<&'w ComponentTicks> { // SAFETY: @@ -298,6 +340,10 @@ impl<'w> InteriorMutableEntityRef<'w> { } } + /// # Safety + /// All [`InteriorMutableEntityRef`] methods take `&self` and thus do not check that there is only one unique reference or multiple shared ones. + /// It is the callers responsibility to make sure that there will never be a mutable reference to a value that has other references pointing to it, + /// and that no arbitrary safe code can access a `&World` while some value is mutably borrowed. #[inline] pub unsafe fn get_mut(&self) -> Option> { // SAFETY: same safety requirements @@ -309,6 +355,10 @@ impl<'w> InteriorMutableEntityRef<'w> { } } + /// # Safety + /// All [`InteriorMutableEntityRef`] methods take `&self` and thus do not check that there is only one unique reference or multiple shared ones. + /// It is the callers responsibility to make sure that there will never be a mutable reference to a value that has other references pointing to it, + /// and that no arbitrary safe code can access a `&World` while some value is mutably borrowed. #[inline] pub unsafe fn get_mut_using_ticks( &self, @@ -347,6 +397,11 @@ impl<'w> InteriorMutableEntityRef<'w> { /// /// Unlike [`InteriorMutableEntityRef::get`], this returns a raw pointer to the component, /// which is only valid while the `'w` borrow of the lifetime is active. + /// + /// # Safety + /// All [`InteriorMutableEntityRef`] methods take `&self` and thus do not check that there is only one unique reference or multiple shared ones. + /// It is the callers responsibility to make sure that there will never be a mutable reference to a value that has other references pointing to it, + /// and that no arbitrary safe code can access a `&World` while some value is mutably borrowed. #[inline] pub unsafe fn get_by_id(&self, component_id: ComponentId) -> Option> { self.world.0.components.get_info(component_id)?; @@ -367,6 +422,11 @@ impl<'w> InteriorMutableEntityRef<'w> { /// /// **You should prefer to use the typed API [`InteriorMutableEntityRef::get_mut`] where possible and only /// use this in cases where the actual types are not known at compile time.** + /// + /// # Safety + /// All [`InteriorMutableEntityRef`] methods take `&self` and thus do not check that there is only one unique reference or multiple shared ones. + /// It is the callers responsibility to make sure that there will never be a mutable reference to a value that has other references pointing to it, + /// and that no arbitrary safe code can access a `&World` while some value is mutably borrowed. #[inline] pub unsafe fn get_mut_by_id(&self, component_id: ComponentId) -> Option> { self.world.0.components.get_info(component_id)?;