add common safety section

Author: jakobhellermann

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<R: Resource>(&self) -> Option<&'w R> {
         self.0.get_resource::<R>()
@@ -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<Ptr<'w>> {
         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<R: Resource>(&self) -> Option<Mut<'w, R>> {
         let component_id = self.0.components.get_resource_id(TypeId::of::<R>())?;
@@ -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<R: 'static>(&self) -> Option<&R> {
         self.0.get_non_send_resource::<R>()
@@ -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<R>(
         &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<R: 'static>(
         &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<T: Component>(&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<T: Component>(&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<T: Component>(&self) -> Option<Mut<'w, T>> {
         // 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<T: Component>(
         &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<Ptr<'w>> {
         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<MutUntyped<'w>> {
         self.world.0.components.get_info(component_id)?;