Add a method to run read-only systems using &World (#8849)

# Objective

Resolves #7558.

Systems that are known to never modify the world implement the trait
`ReadOnlySystem`. This is a perfect place to add a safe API for running
a system with a shared reference to a World.

---

## Changelog

- Added the trait method `ReadOnlySystem::run_readonly`, which allows a
system to be run using `&World`.

crates/bevy_ecs/src/lib.rs

@@ -48,7 +48,7 @@ pub mod prelude {
             adapter as system_adapter,
             adapter::{dbg, error, ignore, info, unwrap, warn},
             Commands, Deferred, In, IntoSystem, Local, NonSend, NonSendMut, ParallelCommands,
-            ParamSet, Query, Res, ResMut, Resource, System, SystemParamFunction,
+            ParamSet, Query, ReadOnlySystem, Res, ResMut, Resource, System, SystemParamFunction,
         },
         world::{FromWorld, World},
     };

crates/bevy_ecs/src/system/system.rs

@@ -52,7 +52,12 @@ pub trait System: Send + Sync + 'static {
     ///   point before this one, with the same exact [`World`]. If `update_archetype_component_access`
     ///   panics (or otherwise does not return for any reason), this method must not be called.
     unsafe fn run_unsafe(&mut self, input: Self::In, world: UnsafeWorldCell) -> Self::Out;
+
     /// Runs the system with the given input in the world.
+    ///
+    /// For [read-only](ReadOnlySystem) systems, see [`run_readonly`], which can be called using `&World`.
+    ///
+    /// [`run_readonly`]: ReadOnlySystem::run_readonly
     fn run(&mut self, input: Self::In, world: &mut World) -> Self::Out {
         let world = world.as_unsafe_world_cell();
         self.update_archetype_component_access(world);
@@ -61,29 +66,36 @@ pub trait System: Send + Sync + 'static {
         // - `update_archetype_component_access` has been called.
         unsafe { self.run_unsafe(input, world) }
     }
+
     /// Applies any [`Deferred`](crate::system::Deferred) system parameters (or other system buffers) of this system to the world.
     ///
     /// This is where [`Commands`](crate::system::Commands) get applied.
     fn apply_deferred(&mut self, world: &mut World);
+
     /// Initialize the system.
     fn initialize(&mut self, _world: &mut World);
+
     /// Update the system's archetype component [`Access`].
     ///
     /// ## Note for implementors
     /// `world` may only be used to access metadata. This can be done in safe code
     /// via functions such as [`UnsafeWorldCell::archetypes`].
     fn update_archetype_component_access(&mut self, world: UnsafeWorldCell);
+
     /// Checks any [`Tick`]s stored on this system and wraps their value if they get too old.
     ///
     /// This method must be called periodically to ensure that change detection behaves correctly.
     /// When using bevy's default configuration, this will be called for you as needed.
     fn check_change_tick(&mut self, change_tick: Tick);
+
     /// Returns the system's default [system sets](crate::schedule::SystemSet).
     fn default_system_sets(&self) -> Vec<Box<dyn crate::schedule::SystemSet>> {
         Vec::new()
     }
+
     /// Gets the tick indicating the last time this system ran.
     fn get_last_run(&self) -> Tick;
+
     /// Overwrites the tick indicating the last time this system ran.
     ///
     /// # Warning
@@ -96,12 +108,30 @@ pub trait System: Send + Sync + 'static {
 /// [`System`] types that do not modify the [`World`] when run.
 /// This is implemented for any systems whose parameters all implement [`ReadOnlySystemParam`].
 ///
+/// Note that systems which perform [deferred](System::apply_deferred) mutations (such as with [`Commands`])
+/// may implement this trait.
+///
 /// [`ReadOnlySystemParam`]: crate::system::ReadOnlySystemParam
+/// [`Commands`]: crate::system::Commands
 ///
 /// # Safety
 ///
-/// This must only be implemented for system types which do not mutate the `World`.
-pub unsafe trait ReadOnlySystem: System {}
+/// This must only be implemented for system types which do not mutate the `World`
+/// when [`System::run_unsafe`] is called.
+pub unsafe trait ReadOnlySystem: System {
+    /// Runs this system with the given input in the world.
+    ///
+    /// Unlike [`System::run`], this can be called with a shared reference to the world,
+    /// since this system is known not to modify the world.
+    fn run_readonly(&mut self, input: Self::In, world: &World) -> Self::Out {
+        let world = world.as_unsafe_world_cell_readonly();
+        self.update_archetype_component_access(world);
+        // SAFETY:
+        // - We have read-only access to the entire world.
+        // - `update_archetype_component_access` has been called.
+        unsafe { self.run_unsafe(input, world) }
+    }
+}
 
 /// A convenience type alias for a boxed [`System`] trait object.
 pub type BoxedSystem<In = (), Out = ()> = Box<dyn System<In = In, Out = Out>>;