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
138
139
140
use crateConIterOfIter;
/// Any regular iterator implements [`IterIntoConcurrentIter`] trait allowing them to be used
/// as a concurrent iterator; i.e., [`ConcurrentIter`], by calling [`iter_into_con_iter`].
///
/// Pulling of elements from the iterator are synchronized and safely shared to threads.
///
/// Therefore, converting an iterator into a concurrent 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.
///
/// [`iter_into_con_iter`]: crate::IterIntoConcurrentIter::iter_into_con_iter
/// [`ConcurrentIter`]: crate::ConcurrentIter
///
/// # Examples
///
/// In the following example, an arbitrary iterator is converted into a concurrent iterator
/// and shared with multiple threads as a shared reference.
///
/// ```
/// use orx_concurrent_iter::*;
///
/// let num_threads = 4;
///
/// 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}!"));
///
/// // converted into a concurrent iterator and shared with multiple threads
/// let con_iter = iter.iter_into_con_iter();
///
/// let process = |_x: String| { /* assume actual work */ };
///
/// std::thread::scope(|s| {
/// for _ in 0..num_threads {
/// s.spawn(|| {
/// while let Some(value) = con_iter.next() {
/// assert!(!value.starts_with('3') && value.ends_with('!'));
/// process(value);
/// }
/// });
/// }
/// });
/// ```
///
/// Similarly, in the following example, computation over elements of a generic
/// iterator are distributed into multiple threads.
///
/// ```
/// use orx_concurrent_iter::*;
///
/// let data: Vec<_> = (0..123).collect();
/// let iter = data.iter().filter(|x| *x % 2 == 0).map(|x| x.to_string());
/// let con_iter = iter.iter_into_con_iter();
///
/// let num_threads = 4;
/// let sum_evens = std::thread::scope(|s| {
/// let mut handles = vec![];
/// for _ in 0..num_threads {
/// handles.push(s.spawn(|| {
/// let mut sum = 0;
/// for x in con_iter.item_puller() {
/// let number: u64 = x.parse().unwrap();
/// sum += number;
/// }
/// sum
/// }));
/// }
/// let mut final_sum = 0;
/// for h in handles {
/// final_sum += h.join().unwrap();
/// }
/// final_sum
/// });
///
/// assert_eq!(sum_evens, 3782);
/// ```