Struct bevy::ecs::query::BatchingStrategy

pub struct BatchingStrategy {
    pub batch_size_limits: Range<usize>,
    pub batches_per_thread: usize,
}

Dictates how a parallel query chunks up large tables/archetypes during iteration.

A parallel query will chunk up large tables and archetypes into chunks of at most a certain batch size.

By default, this batch size is automatically determined by dividing the size of the largest matched archetype by the number of threads (rounded up). This attempts to minimize the overhead of scheduling tasks onto multiple threads, but assumes each entity has roughly the same amount of work to be done, which may not hold true in every workload.

See Query::par_iter for more information.

Fields

batch_size_limits: Range<usize>

The upper and lower limits for how large a batch of entities.

Setting the bounds to the same value will result in a fixed batch size.

Defaults to [1, usize::MAX].

batches_per_thread: usize

The number of batches per thread in the ComputeTaskPool. Increasing this value will decrease the batch size, which may increase the scheduling overhead for the iteration.

Defaults to 1.

Implementations

impl BatchingStrategy

pub const fn new() -> BatchingStrategy

Creates a new unconstrained default batching strategy.

pub const fn fixed(batch_size: usize) -> BatchingStrategy

Declares a batching strategy with a fixed batch size.

Examples found in repository

examples/ecs/parallel_query.rs (line 57)

fn bounce_system(windows: Query<&Window>, mut sprites: Query<(&Transform, &mut Velocity)>) {
    let window = windows.single();
    let width = window.width();
    let height = window.height();
    let left = width / -2.0;
    let right = width / 2.0;
    let bottom = height / -2.0;
    let top = height / 2.0;
    // The default batch size can also be overridden.
    // In this case a batch size of 32 is chosen to limit the overhead of
    // ParallelIterator, since negating a vector is very inexpensive.
    sprites
        .par_iter_mut()
        .batching_strategy(BatchingStrategy::fixed(32))
        .for_each(|(transform, mut v)| {
            if !(left < transform.translation.x
                && transform.translation.x < right
                && bottom < transform.translation.y
                && transform.translation.y < top)
            {
                // For simplicity, just reverse the velocity; don't use realistic bounces
                v.0 = -v.0;
            }
        });
}

pub const fn min_batch_size(self, batch_size: usize) -> BatchingStrategy

Configures the minimum allowed batch size of this instance.

pub const fn max_batch_size(self, batch_size: usize) -> BatchingStrategy

Configures the maximum allowed batch size of this instance.

pub fn batches_per_thread(self, batches_per_thread: usize) -> BatchingStrategy

Configures the number of batches to assign to each thread for this instance.

Trait Implementations

impl Clone for BatchingStrategy

fn clone(&self) -> BatchingStrategy

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.