Skip to content

Commit

Permalink
Enhanced par_for_each and par_for_each_mut docs (#4039)
Browse files Browse the repository at this point in the history
# Objective
Continuation of  #2663 due to git problems - better documentation for Query::par_for_each and par_for_each_mut

## Solution
Going into more detail about the function parameters
  • Loading branch information
Jupp56 committed Feb 25, 2022
1 parent c4e88fe commit b697e73
Showing 1 changed file with 19 additions and 2 deletions.
21 changes: 19 additions & 2 deletions crates/bevy_ecs/src/system/query.rs
Original file line number Diff line number Diff line change
Expand Up @@ -503,10 +503,26 @@ where
};
}

/// Runs `f` on each query result in parallel using the given task pool.
/// Runs `f` on each query result in parallel using the given [`TaskPool`].
///
/// This can only be called for immutable data, see [`Self::par_for_each_mut`] for
/// mutable access.
///
/// # Tasks and batch size
///
/// The items in the query get sorted into batches.
/// Internally, this function spawns a group of futures that each take on a `batch_size` sized section of the items (or less if the division is not perfect).
/// Then, the tasks in the [`TaskPool`] work through these futures.
///
/// You can use this value to tune between maximum multithreading ability (many small batches) and minimum parallelization overhead (few big batches).
/// Rule of thumb: If the function body is (mostly) computationally expensive but there are not many items, a small batch size (=more batches) may help to even out the load.
/// If the body is computationally cheap and you have many items, a large batch size (=fewer batches) avoids spawning additional futures that don't help to even out the load.
///
/// # Arguments
///
///* `task_pool` - The [`TaskPool`] to use
///* `batch_size` - The number of batches to spawn
///* `f` - The function to run on each item in the query
#[inline]
pub fn par_for_each<FN: Fn(<Q::ReadOnlyFetch as Fetch<'w, 's>>::Item) + Send + Sync + Clone>(
&'s self,
Expand All @@ -529,7 +545,8 @@ where
};
}

/// Runs `f` on each query result in parallel using the given task pool.
/// Runs `f` on each query result in parallel using the given [`TaskPool`].
/// See [`Self::par_for_each`] for more details.
#[inline]
pub fn par_for_each_mut<'a, FN: Fn(<Q::Fetch as Fetch<'a, 'a>>::Item) + Send + Sync + Clone>(
&'a mut self,
Expand Down

0 comments on commit b697e73

Please sign in to comment.