Enhanced par_for_each and par_for_each_mut docs (#4039)

# 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
This commit is contained in:
Jupp56 2022-02-25 23:57:01 +00:00
parent c4e88fe4b0
commit b697e73c3d

View file

@ -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 /// This can only be called for immutable data, see [`Self::par_for_each_mut`] for
/// mutable access. /// 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] #[inline]
pub fn par_for_each<FN: Fn(<Q::ReadOnlyFetch as Fetch<'w, 's>>::Item) + Send + Sync + Clone>( pub fn par_for_each<FN: Fn(<Q::ReadOnlyFetch as Fetch<'w, 's>>::Item) + Send + Sync + Clone>(
&'s self, &'s self,
@ -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] #[inline]
pub fn par_for_each_mut<'a, FN: Fn(<Q::Fetch as Fetch<'a, 'a>>::Item) + Send + Sync + Clone>( pub fn par_for_each_mut<'a, FN: Fn(<Q::Fetch as Fetch<'a, 'a>>::Item) + Send + Sync + Clone>(
&'a mut self, &'a mut self,