From 8d1f684e45d76ce97b44db940cbb7b1d2d1019ca Mon Sep 17 00:00:00 2001 From: geo-ant <54497890+geo-ant@users.noreply.github.com> Date: Sun, 13 Nov 2022 17:01:15 +0100 Subject: [PATCH] change feature name to par-iter and add doc example to par_column_iter_mut --- Cargo.toml | 2 +- src/base/iter.rs | 2 +- src/base/matrix.rs | 2 +- src/base/mod.rs | 3 ++- src/base/par_iter.rs | 44 +++++++++++++++++++++++++++++++++----------- tests/core/matrix.rs | 6 +++--- tests/lib.rs | 4 ++-- 7 files changed, 43 insertions(+), 20 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 96356547..cee3130c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -33,7 +33,7 @@ libm = [ "simba/libm" ] libm-force = [ "simba/libm_force" ] macros = [ "nalgebra-macros" ] cuda = [ "cust_core", "simba/cuda" ] -rayon = [ "std", "dep:rayon" ] +par-iter = [ "std", "rayon" ] # Conversion convert-mint = [ "mint" ] diff --git a/src/base/iter.rs b/src/base/iter.rs index 4e1dc21a..220eadd8 100644 --- a/src/base/iter.rs +++ b/src/base/iter.rs @@ -440,7 +440,7 @@ impl<'a, T: Scalar, R: Dim, C: Dim, S: 'a + RawStorageMut> DoubleEndedI } /// implementations for parallel iteration with rayon -#[cfg(feature = "rayon")] +#[cfg(feature = "par-iter")] mod parallel { use super::*; use rayon::iter::plumbing::Producer; diff --git a/src/base/matrix.rs b/src/base/matrix.rs index 700e2f02..2d166d2a 100644 --- a/src/base/matrix.rs +++ b/src/base/matrix.rs @@ -100,7 +100,7 @@ pub type MatrixCross = /// - [Find the min and max components (vector-specific methods) `argmin`, `argmax`, `icamin`, `icamax`…](#find-the-min-and-max-components-vector-specific-methods) /// /// #### Iteration, map, and fold -/// - [Iteration on components, rows, and columns `iter`, `column_iter`…](#iteration-on-components-rows-and-columns) +/// - [Iteration on components, rows, and columns `iter`, `column_iter`, `par_column_iter`…](#iteration-on-components-rows-and-columns) /// - [Elementwise mapping and folding `map`, `fold`, `zip_map`…](#elementwise-mapping-and-folding) /// - [Folding or columns and rows `compress_rows`, `compress_columns`…](#folding-on-columns-and-rows) /// diff --git a/src/base/mod.rs b/src/base/mod.rs index 0f09cc33..f22a53bf 100644 --- a/src/base/mod.rs +++ b/src/base/mod.rs @@ -42,7 +42,8 @@ mod min_max; /// Mechanisms for working with values that may not be initialized. pub mod uninit; -#[cfg(feature = "rayon")] + +#[cfg(feature = "par-iter")] pub mod par_iter; #[cfg(feature = "rkyv-serialize-no-std")] diff --git a/src/base/par_iter.rs b/src/base/par_iter.rs index a551c0a7..1b106e6e 100644 --- a/src/base/par_iter.rs +++ b/src/base/par_iter.rs @@ -15,7 +15,7 @@ use rayon::{iter::plumbing::bridge, prelude::*}; /// /// [`par_column_iter`]: crate::Matrix::par_column_iter /// [`Matrix`]: crate::Matrix -#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))] +#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))] pub struct ParColumnIter<'a, T, R: Dim, Cols: Dim, S: RawStorage> { mat: &'a Matrix, } @@ -27,7 +27,7 @@ impl<'a, T, R: Dim, Cols: Dim, S: RawStorage> ParColumnIter<'a, T, R } } -#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))] +#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))] impl<'a, T, R: Dim, Cols: Dim, S: RawStorage> ParallelIterator for ParColumnIter<'a, T, R, Cols, S> where @@ -48,7 +48,7 @@ where } } -#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))] +#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))] impl<'a, T, R: Dim, Cols: Dim, S: RawStorage> IndexedParallelIterator for ParColumnIter<'a, T, R, Cols, S> where @@ -72,7 +72,7 @@ where } } -#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))] +#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))] impl> Matrix where T: Send + Sync + Scalar, @@ -83,7 +83,7 @@ where /// if *mutable* access to the columns is required, use [`par_column_iter_mut`] /// instead. /// - /// **Example** + /// # Example /// Using parallel column iterators to calculate the sum of the maximum /// elements in each column: /// ``` @@ -110,7 +110,7 @@ where } } -#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))] +#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))] /// A rayon parallel iterator through the mutable columns of a matrix pub struct ParColumnIterMut< 'a, @@ -122,7 +122,7 @@ pub struct ParColumnIterMut< mat: &'a mut Matrix, } -#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))] +#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))] impl<'a, T, R, Cols, S> ParColumnIterMut<'a, T, R, Cols, S> where R: Dim, @@ -135,7 +135,7 @@ where } } -#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))] +#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))] impl<'a, T, R, Cols, S> ParallelIterator for ParColumnIterMut<'a, T, R, Cols, S> where R: Dim, @@ -157,7 +157,7 @@ where } } -#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))] +#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))] impl<'a, T, R, Cols, S> IndexedParallelIterator for ParColumnIterMut<'a, T, R, Cols, S> where R: Dim, @@ -183,14 +183,36 @@ where } } -#[cfg_attr(doc_cfg, doc(cfg(feature = "rayon")))] +#[cfg_attr(doc_cfg, doc(cfg(feature = "par-iter")))] impl + RawStorageMut> Matrix where T: Send + Sync + Scalar, S: Sync, { - /// Mutably iterate through the columns of this matrix in parallel using rayon + /// Mutably iterate through the columns of this matrix in parallel using rayon. + /// Allows mutable access to the columns in parallel using mutable references. + /// If mutable access to the columns is not required rather use [`par_column_iter`] + /// instead. + /// + /// # Example + /// Normalize each column of a matrix with respect to its own maximum value. + /// + /// ``` + /// use nalgebra::{dmatrix,DMatrix}; + /// use rayon::prelude::*; + /// + /// let mut matrix : DMatrix = + /// dmatrix![2.,4.,6.; + /// 1.,2.,3.]; + /// matrix.par_column_iter_mut().for_each(|mut col| col /= col.max()); + /// + /// assert_eq!(matrix, + /// dmatrix![1. ,1. , 1.; + /// 0.5,0.5,0.5]); + /// ``` + /// + /// [`par_column_iter`]: crate::Matrix::par_column_iter pub fn par_column_iter_mut(&mut self) -> ParColumnIterMut<'_, T, R, Cols, S> { ParColumnIterMut::new(self) } diff --git a/tests/core/matrix.rs b/tests/core/matrix.rs index 12f5308e..603897af 100644 --- a/tests/core/matrix.rs +++ b/tests/core/matrix.rs @@ -1200,7 +1200,7 @@ fn column_iteration_double_ended() { } #[test] -#[cfg(feature = "rayon")] +#[cfg(feature = "par-iter")] fn parallel_column_iteration() { use nalgebra::dmatrix; use rayon::prelude::*; @@ -1222,7 +1222,7 @@ fn parallel_column_iteration() { } #[test] -#[cfg(feature = "rayon")] +#[cfg(feature = "par-iter")] fn column_iteration_mut_double_ended() { let dmat = nalgebra::dmatrix![ 13,14,15,16,17; @@ -1241,7 +1241,7 @@ fn column_iteration_mut_double_ended() { } #[test] -#[cfg(feature = "rayon")] +#[cfg(feature = "par-iter")] fn parallel_column_iteration_mut() { use rayon::prelude::*; let mut first = DMatrix::::zeros(400, 300); diff --git a/tests/lib.rs b/tests/lib.rs index fb13b3ae..6e4238e5 100644 --- a/tests/lib.rs +++ b/tests/lib.rs @@ -10,8 +10,8 @@ compile_error!( ); // make sure to test the parallel iterators for all builds that do not require no_std -#[cfg(all(feature = "std", not(feature = "rayon")))] -compile_error!("Please additionally enable the `rayon` feature to compile and run the tests"); +#[cfg(all(feature = "std", not(feature = "par-iter")))] +compile_error!("Please additionally enable the `par-iter` feature to compile and run the tests"); #[cfg(all(feature = "debug", feature = "compare", feature = "rand"))] #[macro_use]