orx-parallel 3.4.0

High performance, configurable and expressive parallel computation library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

use crate::{Params, computational_variants::Par, runner::DefaultRunner};
use orx_concurrent_iter::{IterIntoConcurrentIter, implementations::ConIterOfIter};

/// Any regular iterator implements [`IterIntoParIter`] trait allowing them to be used
/// as a parallel iterator; i.e., [`ParIter`], by calling [`iter_into_par`].
///
/// Pulling of elements from the iterator are synchronized and safely shared to threads.
///
/// Therefore, converting an iterator into a parallel iterator is most useful whenever
/// the work to be done on each element is a larger task than just yielding elements by the
/// underlying collection or generator.
///
/// Note that every [`IterIntoConcurrentIter`] type automatically implements [`IterIntoParIter`].
///
/// [`iter_into_par`]: crate::IterIntoParIter::iter_into_par
/// [`ParIter`]: crate::ParIter
/// [`IterIntoConcurrentIter`]: orx_concurrent_iter::IterIntoConcurrentIter
///
/// # Examples
///
/// In the following example, an arbitrary iterator is converted into a parallel iterator
/// and shared with multiple threads as a shared reference.
///
/// ```
/// use orx_parallel::*;
///
/// let data: Vec<_> = (0..100).map(|x| x.to_string()).collect();
///
/// // an arbitrary iterator
/// let iter = data
///     .into_iter()
///     .filter(|x| !x.starts_with('3'))
///     .map(|x| format!("{x}!"));
///
/// // convert arbitrary iterator into ParIter
/// let par_iter = iter.iter_into_par();
/// let num_characters = par_iter.map(|x| x.len()).sum();
///
/// assert_eq!(num_characters, 258);
/// ```
///
/// Similarly, in the following example, computation over elements of a generic
/// iterator are distributed into multiple threads.
///
/// ```
/// use orx_parallel::*;
///
/// let data: Vec<_> = (0..123).collect();
///
/// // arbitrary iterator
/// let iter = data.iter().filter(|x| *x % 2 == 0).map(|x| x.to_string());
///
/// // parallel computation
/// let sum_evens = iter
///     .iter_into_par()
///     .map(|x| x.parse::<u64>().unwrap())
///     .sum();
///
/// assert_eq!(sum_evens, 3782);
/// ```
pub trait IterIntoParIter: Iterator {
    /// Any regular iterator implements [`IterIntoParIter`] trait allowing them to be used
    /// as a parallel iterator; i.e., [`ParIter`], by calling [`iter_into_par`].
    ///
    /// Pulling of elements from the iterator are synchronized and safely shared to threads.
    ///
    /// Therefore, converting an iterator into a parallel iterator is most useful whenever
    /// the work to be done on each element is a larger task than just yielding elements by the
    /// underlying collection or generator.
    ///
    /// Note that every [`IterIntoConcurrentIter`] type automatically implements [`IterIntoParIter`].
    ///
    /// [`iter_into_par`]: crate::IterIntoParIter::iter_into_par
    /// [`ParIter`]: crate::ParIter
    /// [`IterIntoConcurrentIter`]: orx_concurrent_iter::IterIntoConcurrentIter
    ///
    /// # Examples
    ///
    /// In the following example, an arbitrary iterator is converted into a parallel iterator
    /// and shared with multiple threads as a shared reference.
    ///
    /// ```
    /// use orx_parallel::*;
    ///
    /// let data: Vec<_> = (0..100).map(|x| x.to_string()).collect();
    ///
    /// // an arbitrary iterator
    /// let iter = data
    ///     .into_iter()
    ///     .filter(|x| !x.starts_with('3'))
    ///     .map(|x| format!("{x}!"));
    ///
    /// // convert arbitrary iterator into ParIter
    /// let par_iter = iter.iter_into_par();
    /// let num_characters = par_iter.map(|x| x.len()).sum();
    ///
    /// assert_eq!(num_characters, 258);
    /// ```
    ///
    /// Similarly, in the following example, computation over elements of a generic
    /// iterator are distributed into multiple threads.
    ///
    /// ```
    /// use orx_parallel::*;
    ///
    /// let data: Vec<_> = (0..123).collect();
    ///
    /// // arbitrary iterator
    /// let iter = data.iter().filter(|x| *x % 2 == 0).map(|x| x.to_string());
    ///
    /// // parallel computation
    /// let sum_evens = iter
    ///     .iter_into_par()
    ///     .map(|x| x.parse::<u64>().unwrap())
    ///     .sum();
    ///
    /// assert_eq!(sum_evens, 3782);
    /// ```
    fn iter_into_par(self) -> Par<ConIterOfIter<Self>, DefaultRunner>
    where
        Self: Sized,
        Self::Item: Send;
}

impl<I> IterIntoParIter for I
where
    I: Iterator,
    I::Item: Send + Sync,
{
    fn iter_into_par(self) -> Par<ConIterOfIter<Self>, DefaultRunner> {
        Par::new(
            Default::default(),
            Params::default(),
            self.iter_into_con_iter(),
        )
    }
}