bevy_ecs/system/commands/
parallel_scope.rs

1use bevy_utils::Parallel;
2
3use crate::{
4    self as bevy_ecs,
5    entity::Entities,
6    prelude::World,
7    system::{Deferred, SystemBuffer, SystemMeta, SystemParam},
8};
9
10use super::{CommandQueue, Commands};
11
12#[derive(Default)]
13struct ParallelCommandQueue {
14    thread_queues: Parallel<CommandQueue>,
15}
16
17/// An alternative to [`Commands`] that can be used in parallel contexts, such as those
18/// in [`Query::par_iter`](crate::system::Query::par_iter).
19///
20/// For cases where multiple non-computation-heavy (lightweight) bundles of the same
21/// [`Bundle`](crate::prelude::Bundle) type need to be spawned, consider using
22/// [`Commands::spawn_batch`] for better performance.
23///
24/// Note: Because command application order will depend on how many threads are ran, non-commutative commands may result in non-deterministic results.
25///
26/// Example:
27/// ```
28/// # use bevy_ecs::prelude::*;
29/// # use bevy_tasks::ComputeTaskPool;
30/// #
31/// # #[derive(Component)]
32/// # struct Velocity;
33/// # impl Velocity { fn magnitude(&self) -> f32 { 42.0 } }
34/// fn parallel_command_system(
35///     mut query: Query<(Entity, &Velocity)>,
36///     par_commands: ParallelCommands
37/// ) {
38///     query.par_iter().for_each(|(entity, velocity)| {
39///         if velocity.magnitude() > 10.0 {
40///             par_commands.command_scope(|mut commands| {
41///                 commands.entity(entity).despawn();
42///             });
43///         }
44///     });
45/// }
46/// # bevy_ecs::system::assert_is_system(parallel_command_system);
47/// ```
48#[derive(SystemParam)]
49pub struct ParallelCommands<'w, 's> {
50    state: Deferred<'s, ParallelCommandQueue>,
51    entities: &'w Entities,
52}
53
54impl SystemBuffer for ParallelCommandQueue {
55    #[inline]
56    fn apply(&mut self, _system_meta: &SystemMeta, world: &mut World) {
57        #[cfg(feature = "trace")]
58        let _system_span = _system_meta.commands_span.enter();
59        for cq in self.thread_queues.iter_mut() {
60            cq.apply(world);
61        }
62    }
63}
64
65impl<'w, 's> ParallelCommands<'w, 's> {
66    /// Temporarily provides access to the [`Commands`] for the current thread.
67    ///
68    /// For an example, see the type-level documentation for [`ParallelCommands`].
69    pub fn command_scope<R>(&self, f: impl FnOnce(Commands) -> R) -> R {
70        self.state.thread_queues.scope(|queue| {
71            let commands = Commands::new_from_entities(queue, self.entities);
72            f(commands)
73        })
74    }
75}
bevy_ecs/system/commands/parallel_scope.rs

bevy_ecs/system/commands/
parallel_scope.rs
