Struct bevy::ecs::batching::BatchingStrategy

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

Dictates how a parallel operation chunks up large quantities during iteration.

A parallel query will chunk up large tables and archetypes into chunks of at most a certain batch size. Similarly, a parallel event reader will chunk up the remaining events.

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, EventReader::par_read for more information.

Fields

batch_size_limits: Range<usize>

The upper and lower limits for 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 61)

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.

pub fn calc_batch_size( &self, max_items: impl FnOnce() -> usize, thread_count: usize ) -> usize

Calculate the batch size according to the given thread count and max item count. The count is provided as a closure so that it can be calculated only if needed.

Panics

Panics if thread_count is 0.

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.

impl Debug for BatchingStrategy

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for BatchingStrategy

fn default() -> BatchingStrategy

Returns the “default value” for a type.