1/****************************************************************************
2**
3** Copyright (C) 2016 The Qt Company Ltd.
4** Contact: https://www.qt.io/licensing/
5**
6** This file is part of the QtConcurrent module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial License Usage
10** Licensees holding valid commercial Qt licenses may use this file in
11** accordance with the commercial license agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and The Qt Company. For licensing terms
14** and conditions see https://www.qt.io/terms-conditions. For further
15** information use the contact form at https://www.qt.io/contact-us.
16**
17** GNU Lesser General Public License Usage
18** Alternatively, this file may be used under the terms of the GNU Lesser
19** General Public License version 3 as published by the Free Software
20** Foundation and appearing in the file LICENSE.LGPL3 included in the
21** packaging of this file. Please review the following information to
22** ensure the GNU Lesser General Public License version 3 requirements
23** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
24**
25** GNU General Public License Usage
26** Alternatively, this file may be used under the terms of the GNU
27** General Public License version 2.0 or (at your option) the GNU General
28** Public license version 3 or any later version approved by the KDE Free
29** Qt Foundation. The licenses are as published by the Free Software
30** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
31** included in the packaging of this file. Please review the following
32** information to ensure the GNU General Public License requirements will
33** be met: https://www.gnu.org/licenses/gpl-2.0.html and
34** https://www.gnu.org/licenses/gpl-3.0.html.
35**
36** $QT_END_LICENSE$
37**
38****************************************************************************/
39
40/*!
41 \page qtconcurrentfilter.html
42 \title Concurrent Filter and Filter-Reduce
43 \ingroup thread
44
45 The QtConcurrent::filter(), QtConcurrent::filtered() and
46 QtConcurrent::filteredReduced() functions filter items in a sequence such
47 as a QList in parallel. QtConcurrent::filter() modifies a
48 sequence in-place, QtConcurrent::filtered() returns a new sequence
49 containing the filtered content, and QtConcurrent::filteredReduced()
50 returns a single result.
51
52 These functions are part of the \l {Qt Concurrent} framework.
53
54 Each of the above functions have a blocking variant that returns the final
55 result instead of a QFuture. You use them in the same way as the
56 asynchronous variants.
57
58 \snippet code/src_concurrent_qtconcurrentfilter.cpp 6
59
60 Note that the result types above are not QFuture objects, but real result
61 types (in this case, QStringList and QSet<QString>).
62
63 \section1 Concurrent Filter
64
65 QtConcurrent::filtered() takes an input sequence and a filter function.
66 This filter function is then called for each item in the sequence, and a
67 new sequence containing the filtered values is returned.
68
69 The filter function must be of the form:
70
71 \snippet code/src_concurrent_qtconcurrentfilter.cpp 0
72
73 T must match the type stored in the sequence. The function returns \c true if
74 the item should be kept, false if it should be discarded.
75
76 This example shows how to keep strings that are all lower-case from a
77 QStringList:
78
79 \snippet code/src_concurrent_qtconcurrentfilter.cpp 1
80
81 The results of the filter are made available through QFuture. See the
82 QFuture and QFutureWatcher documentation for more information on how to
83 use QFuture in your applications.
84
85 If you want to modify a sequence in-place, use QtConcurrent::filter():
86
87 \snippet code/src_concurrent_qtconcurrentfilter.cpp 2
88
89 Since the sequence is modified in place, QtConcurrent::filter() does not
90 return any results via QFuture. However, you can still use QFuture and
91 QFutureWatcher to monitor the status of the filter.
92
93 \section1 Concurrent Filter-Reduce
94
95 QtConcurrent::filteredReduced() is similar to QtConcurrent::filtered(),
96 but instead of returning a sequence with the filtered results, the results
97 are combined into a single value using a reduce function.
98
99 The reduce function must be of the form:
100
101 \snippet code/src_concurrent_qtconcurrentfilter.cpp 3
102
103 T is the type of the final result, U is the type of items being filtered.
104 Note that the return value and return type of the reduce function are not
105 used.
106
107 Call QtConcurrent::filteredReduced() like this:
108
109 \snippet code/src_concurrent_qtconcurrentfilter.cpp 4
110
111 The reduce function will be called once for each result kept by the filter
112 function, and should merge the \e{intermediate} into the \e{result}
113 variable. QtConcurrent::filteredReduced() guarantees that only one thread
114 will call reduce at a time, so using a mutex to lock the result variable
115 is not necessary. The QtConcurrent::ReduceOptions enum provides a way to
116 control the order in which the reduction is done.
117
118 \section1 Additional API Features
119
120 \section2 Using Iterators instead of Sequence
121
122 Each of the above functions has a variant that takes an iterator range
123 instead of a sequence. You use them in the same way as the sequence
124 variants:
125
126 \snippet code/src_concurrent_qtconcurrentfilter.cpp 5
127
128
129 \section2 Using Member Functions
130
131 QtConcurrent::filter(), QtConcurrent::filtered(), and
132 QtConcurrent::filteredReduced() accept pointers to member functions.
133 The member function class type must match the type stored in the sequence:
134
135 \snippet code/src_concurrent_qtconcurrentfilter.cpp 7
136
137 Note that when using QtConcurrent::filteredReduced(), you can mix the use of
138 normal and member functions freely:
139
140 \snippet code/src_concurrent_qtconcurrentfilter.cpp 8
141
142 \section2 Using Function Objects
143
144 QtConcurrent::filter(), QtConcurrent::filtered(), and
145 QtConcurrent::filteredReduced() accept function objects
146 for the filter function. These function objects can be used to
147 add state to a function call:
148
149 \snippet code/src_concurrent_qtconcurrentfilter.cpp 13
150
151 For the reduce function, function objects are not directly
152 supported. Function objects can, however, be used
153 when the type of the reduction result is explicitly specified:
154
155 \snippet code/src_concurrent_qtconcurrentfilter.cpp 14
156
157 \section2 Using Lambda Expressions
158
159 QtConcurrent::filter(), QtConcurrent::filtered(), and
160 QtConcurrent::filteredReduced() accept lambda expressions for the filter and
161 reduce function:
162
163 \snippet code/src_concurrent_qtconcurrentfilter.cpp 15
164
165 When using QtConcurrent::filteredReduced() or
166 QtConcurrent::blockingFilteredReduced(), you can mix the use of normal
167 functions, member functions and lambda expressions freely.
168
169 \snippet code/src_concurrent_qtconcurrentfilter.cpp 16
170
171 For the reduce function, lambda expressions are not directly supported.
172 Lambda expressions can, however, be used when the type of the reduction
173 result is explicitly specified:
174
175 \snippet code/src_concurrent_qtconcurrentfilter.cpp 17
176
177 \section2 Wrapping Functions that Take Multiple Arguments
178
179 If you want to use a filter function takes more than one argument, you can
180 use a lambda function or \c std::bind() to transform it onto a function that
181 takes one argument.
182
183 As an example, we use QString::contains():
184
185 \snippet code/src_concurrent_qtconcurrentfilter.cpp 9
186
187 QString::contains() takes 2 arguments (including the "this" pointer) and
188 can't be used with QtConcurrent::filtered() directly, because
189 QtConcurrent::filtered() expects a function that takes one argument. To
190 use QString::contains() with QtConcurrent::filtered() we have to provide a
191 value for the \e regexp argument:
192
193 \snippet code/src_concurrent_qtconcurrentfilter.cpp 12
194*/
195
196/*!
197 \class QtConcurrent::qValueType
198 \inmodule QtConcurrent
199 \internal
200*/
201
202/*!
203 \class QtConcurrent::qValueType<const T*>
204 \inmodule QtConcurrent
205 \internal
206*/
207
208
209/*!
210 \class QtConcurrent::qValueType<T*>
211 \inmodule QtConcurrent
212 \internal
213*/
214
215/*!
216 \class QtConcurrent::FilterKernel
217 \inmodule QtConcurrent
218 \internal
219*/
220
221/*!
222 \class QtConcurrent::FilteredReducedKernel
223 \inmodule QtConcurrent
224 \internal
225*/
226
227/*!
228 \class QtConcurrent::FilteredEachKernel
229 \inmodule QtConcurrent
230 \internal
231*/
232
233/*!
234 \fn [QtConcurrent-1] template <typename Sequence, typename KeepFunctor, typename ReduceFunctor> ThreadEngineStarter<void> QtConcurrent::filterInternal(Sequence &sequence, KeepFunctor keep, ReduceFunctor reduce)
235 \internal
236*/
237
238/*!
239 \fn template <typename Sequence, typename KeepFunctor> QFuture<void> QtConcurrent::filter(QThreadPool *pool, Sequence &sequence, KeepFunctor filterFunction)
240
241 Calls \a filterFunction once for each item in \a sequence.
242 All calls to \a filterFunction are invoked from the threads taken from the QThreadPool \a pool.
243 If \a filterFunction returns \c true, the item is kept in \a sequence;
244 otherwise, the item is removed from \a sequence.
245
246 Note that this method doesn't have an overload working with iterators, because
247 it invalidates the iterators of the sequence it operates on.
248
249 \sa {Concurrent Filter and Filter-Reduce}
250*/
251
252/*!
253 \fn template <typename Sequence, typename KeepFunctor> QFuture<void> QtConcurrent::filter(Sequence &sequence, KeepFunctor filterFunction)
254
255 Calls \a filterFunction once for each item in \a sequence. If
256 \a filterFunction returns \c true, the item is kept in \a sequence;
257 otherwise, the item is removed from \a sequence.
258
259 Note that this method doesn't have an overload working with iterators, because
260 it invalidates the iterators of the sequence it operates on.
261
262 \sa {Concurrent Filter and Filter-Reduce}
263*/
264
265/*!
266 \fn template <typename Sequence, typename KeepFunctor> QFuture<Sequence::value_type> QtConcurrent::filtered(QThreadPool *pool, Sequence &&sequence, KeepFunctor filterFunction)
267
268 Calls \a filterFunction once for each item in \a sequence and returns a
269 new Sequence of kept items. All calls to \a filterFunction are invoked from the threads
270 taken from the QThreadPool \a pool. If \a filterFunction returns \c true, a copy of
271 the item is put in the new Sequence. Otherwise, the item will \e not
272 appear in the new Sequence.
273
274 \sa {Concurrent Filter and Filter-Reduce}
275*/
276
277/*!
278 \fn template <typename Sequence, typename KeepFunctor> QFuture<Sequence::value_type> QtConcurrent::filtered(Sequence &&sequence, KeepFunctor filterFunction)
279
280 Calls \a filterFunction once for each item in \a sequence and returns a
281 new Sequence of kept items. If \a filterFunction returns \c true, a copy of
282 the item is put in the new Sequence. Otherwise, the item will \e not
283 appear in the new Sequence.
284
285 \sa {Concurrent Filter and Filter-Reduce}
286*/
287
288/*!
289 \fn template <typename Iterator, typename KeepFunctor> QFuture<typename QtConcurrent::qValueType<Iterator>::value_type> QtConcurrent::filtered(QThreadPool *pool, Iterator begin, Iterator end, KeepFunctor filterFunction)
290
291 Calls \a filterFunction once for each item from \a begin to \a end and
292 returns a new Sequence of kept items. All calls to \a filterFunction are invoked from the threads
293 taken from the QThreadPool \a pool. If \a filterFunction returns \c true, a
294 copy of the item is put in the new Sequence. Otherwise, the item will
295 \e not appear in the new Sequence.
296
297 \sa {Concurrent Filter and Filter-Reduce}
298*/
299
300/*!
301 \fn template <typename Iterator, typename KeepFunctor> QFuture<typename QtConcurrent::qValueType<Iterator>::value_type> QtConcurrent::filtered(Iterator begin, Iterator end, KeepFunctor filterFunction)
302
303 Calls \a filterFunction once for each item from \a begin to \a end and
304 returns a new Sequence of kept items. If \a filterFunction returns \c true, a
305 copy of the item is put in the new Sequence. Otherwise, the item will
306 \e not appear in the new Sequence.
307
308 \sa {Concurrent Filter and Filter-Reduce}
309*/
310
311/*!
312 \fn template <typename ResultType, typename Sequence, typename KeepFunctor, typename ReduceFunctor> QFuture<ResultType> QtConcurrent::filteredReduced(QThreadPool *pool, Sequence &&sequence, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions)
313
314 Calls \a filterFunction once for each item in \a sequence.
315 All calls to \a filterFunction are invoked from the threads taken from the QThreadPool \a pool.
316 If \a filterFunction returns \c true for an item, that item is then passed to
317 \a reduceFunction. In other words, the return value is the result of
318 \a reduceFunction for each item where \a filterFunction returns \c true.
319
320 Note that while \a filterFunction is called concurrently, only one thread
321 at a time will call \a reduceFunction. The order in which \a reduceFunction
322 is called is undefined if \a reduceOptions is
323 QtConcurrent::UnorderedReduce. If \a reduceOptions is
324 QtConcurrent::OrderedReduce, \a reduceFunction is called in the order of
325 the original sequence.
326
327 \sa {Concurrent Filter and Filter-Reduce}
328*/
329
330/*!
331 \fn template <typename ResultType, typename Sequence, typename KeepFunctor, typename ReduceFunctor> QFuture<ResultType> QtConcurrent::filteredReduced(Sequence &&sequence, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions)
332
333 Calls \a filterFunction once for each item in \a sequence. If
334 \a filterFunction returns \c true for an item, that item is then passed to
335 \a reduceFunction. In other words, the return value is the result of
336 \a reduceFunction for each item where \a filterFunction returns \c true.
337
338 Note that while \a filterFunction is called concurrently, only one thread
339 at a time will call \a reduceFunction. The order in which \a reduceFunction
340 is called is undefined if \a reduceOptions is
341 QtConcurrent::UnorderedReduce. If \a reduceOptions is
342 QtConcurrent::OrderedReduce, \a reduceFunction is called in the order of
343 the original sequence.
344
345 \sa {Concurrent Filter and Filter-Reduce}
346*/
347
348/*!
349 \fn template <typename ResultType, typename Sequence, typename KeepFunctor, typename ReduceFunctor, typename InitialValueType> QFuture<ResultType> QtConcurrent::filteredReduced(QThreadPool *pool, Sequence &&sequence, KeepFunctor filterFunction, ReduceFunctor reduceFunction, InitialValueType &&initialValue, QtConcurrent::ReduceOptions reduceOptions)
350
351 Calls \a filterFunction once for each item in \a sequence.
352 All calls to \a filterFunction are invoked from the threads taken from the QThreadPool \a pool.
353 If \a filterFunction returns \c true for an item, that item is then passed to
354 \a reduceFunction. In other words, the return value is the result of
355 \a reduceFunction for each item where \a filterFunction returns \c true.
356 The result value is initialized to \a initialValue when the function is
357 called, and the first call to \a reduceFunction will operate on
358 this value.
359
360 Note that while \a filterFunction is called concurrently, only one thread
361 at a time will call \a reduceFunction. The order in which \a reduceFunction
362 is called is undefined if \a reduceOptions is
363 QtConcurrent::UnorderedReduce. If \a reduceOptions is
364 QtConcurrent::OrderedReduce, \a reduceFunction is called in the order of
365 the original sequence.
366
367 \sa {Concurrent Filter and Filter-Reduce}
368*/
369
370/*!
371 \fn template <typename ResultType, typename Sequence, typename KeepFunctor, typename ReduceFunctor, typename InitialValueType> QFuture<ResultType> QtConcurrent::filteredReduced(Sequence &&sequence, KeepFunctor filterFunction, ReduceFunctor reduceFunction, InitialValueType &&initialValue, QtConcurrent::ReduceOptions reduceOptions)
372
373 Calls \a filterFunction once for each item in \a sequence. If
374 \a filterFunction returns \c true for an item, that item is then passed to
375 \a reduceFunction. In other words, the return value is the result of
376 \a reduceFunction for each item where \a filterFunction returns \c true.
377 The result value is initialized to \a initialValue when the function is
378 called, and the first call to \a reduceFunction will operate on
379 this value.
380
381 Note that while \a filterFunction is called concurrently, only one thread
382 at a time will call \a reduceFunction. The order in which \a reduceFunction
383 is called is undefined if \a reduceOptions is
384 QtConcurrent::UnorderedReduce. If \a reduceOptions is
385 QtConcurrent::OrderedReduce, \a reduceFunction is called in the order of
386 the original sequence.
387
388 \sa {Concurrent Filter and Filter-Reduce}
389*/
390
391/*!
392 \fn template <typename ResultType, typename Iterator, typename KeepFunctor, typename ReduceFunctor> QFuture<ResultType> QtConcurrent::filteredReduced(QThreadPool *pool, Iterator begin, Iterator end, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions)
393
394 Calls \a filterFunction once for each item from \a begin to \a end.
395 All calls to \a filterFunction are invoked from the threads taken from the QThreadPool \a pool.
396 If \a filterFunction returns \c true for an item, that item is then passed to
397 \a reduceFunction. In other words, the return value is the result of
398 \a reduceFunction for each item where \a filterFunction returns \c true.
399
400 Note that while \a filterFunction is called concurrently, only one thread
401 at a time will call \a reduceFunction. The order in which
402 \a reduceFunction is called is undefined if \a reduceOptions is
403 QtConcurrent::UnorderedReduce. If \a reduceOptions is
404 QtConcurrent::OrderedReduce, the \a reduceFunction is called in the order
405 of the original sequence.
406
407 \sa {Concurrent Filter and Filter-Reduce}
408*/
409
410/*!
411 \fn template <typename ResultType, typename Iterator, typename KeepFunctor, typename ReduceFunctor> QFuture<ResultType> QtConcurrent::filteredReduced(Iterator begin, Iterator end, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions)
412
413 Calls \a filterFunction once for each item from \a begin to \a end. If
414 \a filterFunction returns \c true for an item, that item is then passed to
415 \a reduceFunction. In other words, the return value is the result of
416 \a reduceFunction for each item where \a filterFunction returns \c true.
417
418 Note that while \a filterFunction is called concurrently, only one thread
419 at a time will call \a reduceFunction. The order in which
420 \a reduceFunction is called is undefined if \a reduceOptions is
421 QtConcurrent::UnorderedReduce. If \a reduceOptions is
422 QtConcurrent::OrderedReduce, the \a reduceFunction is called in the order
423 of the original sequence.
424
425 \sa {Concurrent Filter and Filter-Reduce}
426*/
427
428/*!
429 \fn template <typename ResultType, typename Iterator, typename KeepFunctor, typename ReduceFunctor, typename InitialValueType> QFuture<ResultType> QtConcurrent::filteredReduced(QThreadPool *pool, Iterator begin, Iterator end, KeepFunctor filterFunction, ReduceFunctor reduceFunction, InitialValueType &&initialValue, QtConcurrent::ReduceOptions reduceOptions)
430
431 Calls \a filterFunction once for each item from \a begin to \a end.
432 All calls to \a filterFunction are invoked from the threads taken from the QThreadPool \a pool.
433 If \a filterFunction returns \c true for an item, that item is then passed to
434 \a reduceFunction. In other words, the return value is the result of
435 \a reduceFunction for each item where \a filterFunction returns \c true.
436 The result value is initialized to \a initialValue when the function is
437 called, and the first call to \a reduceFunction will operate on
438 this value.
439
440 Note that while \a filterFunction is called concurrently, only one thread
441 at a time will call \a reduceFunction. The order in which
442 \a reduceFunction is called is undefined if \a reduceOptions is
443 QtConcurrent::UnorderedReduce. If \a reduceOptions is
444 QtConcurrent::OrderedReduce, the \a reduceFunction is called in the order
445 of the original sequence.
446
447 \sa {Concurrent Filter and Filter-Reduce}
448*/
449
450/*!
451 \fn template <typename ResultType, typename Iterator, typename KeepFunctor, typename ReduceFunctor, typename InitialValueType> QFuture<ResultType> QtConcurrent::filteredReduced(Iterator begin, Iterator end, KeepFunctor filterFunction, ReduceFunctor reduceFunction, InitialValueType &&initialValue, QtConcurrent::ReduceOptions reduceOptions)
452
453 Calls \a filterFunction once for each item from \a begin to \a end. If
454 \a filterFunction returns \c true for an item, that item is then passed to
455 \a reduceFunction. In other words, the return value is the result of
456 \a reduceFunction for each item where \a filterFunction returns \c true.
457 The result value is initialized to \a initialValue when the function is
458 called, and the first call to \a reduceFunction will operate on
459 this value.
460
461 Note that while \a filterFunction is called concurrently, only one thread
462 at a time will call \a reduceFunction. The order in which
463 \a reduceFunction is called is undefined if \a reduceOptions is
464 QtConcurrent::UnorderedReduce. If \a reduceOptions is
465 QtConcurrent::OrderedReduce, the \a reduceFunction is called in the order
466 of the original sequence.
467
468 \sa {Concurrent Filter and Filter-Reduce}
469*/
470
471/*!
472 \fn template <typename Sequence, typename KeepFunctor> void QtConcurrent::blockingFilter(QThreadPool *pool, Sequence &sequence, KeepFunctor filterFunction)
473
474 Calls \a filterFunction once for each item in \a sequence.
475 All calls to \a filterFunction are invoked from the threads taken from the QThreadPool \a pool.
476 If \a filterFunction returns \c true, the item is kept in \a sequence;
477 otherwise, the item is removed from \a sequence.
478
479 Note that this method doesn't have an overload working with iterators, because
480 it invalidates the iterators of the sequence it operates on.
481
482 \note This function will block until all items in the sequence have been processed.
483
484 \sa {Concurrent Filter and Filter-Reduce}
485*/
486
487/*!
488 \fn template <typename Sequence, typename KeepFunctor> void QtConcurrent::blockingFilter(Sequence &sequence, KeepFunctor filterFunction)
489
490 Calls \a filterFunction once for each item in \a sequence. If
491 \a filterFunction returns \c true, the item is kept in \a sequence;
492 otherwise, the item is removed from \a sequence.
493
494 Note that this method doesn't have an overload working with iterators, because
495 it invalidates the iterators of the sequence it operates on.
496
497 \note This function will block until all items in the sequence have been processed.
498
499 \sa {Concurrent Filter and Filter-Reduce}
500*/
501
502/*!
503 \fn template <typename Sequence, typename KeepFunctor> Sequence QtConcurrent::blockingFiltered(QThreadPool *pool, Sequence &&sequence, KeepFunctor filterFunction)
504
505 Calls \a filterFunction once for each item in \a sequence and returns a
506 new Sequence of kept items. All calls to \a filterFunction are invoked from the threads
507 taken from the QThreadPool \a pool. If \a filterFunction returns \c true, a copy of
508 the item is put in the new Sequence. Otherwise, the item will \e not
509 appear in the new Sequence.
510
511 \note This function will block until all items in the sequence have been processed.
512
513 \sa filtered(), {Concurrent Filter and Filter-Reduce}
514*/
515
516/*!
517 \fn template <typename Sequence, typename KeepFunctor> Sequence QtConcurrent::blockingFiltered(Sequence &&sequence, KeepFunctor filterFunction)
518
519 Calls \a filterFunction once for each item in \a sequence and returns a
520 new Sequence of kept items. If \a filterFunction returns \c true, a copy of
521 the item is put in the new Sequence. Otherwise, the item will \e not
522 appear in the new Sequence.
523
524 \note This function will block until all items in the sequence have been processed.
525
526 \sa filtered(), {Concurrent Filter and Filter-Reduce}
527*/
528
529/*!
530 \fn template <typename OutputSequence, typename Iterator, typename KeepFunctor> OutputSequence QtConcurrent::blockingFiltered(QThreadPool *pool, Iterator begin, Iterator end, KeepFunctor filterFunction)
531
532 Calls \a filterFunction once for each item from \a begin to \a end and
533 returns a new Sequence of kept items. All calls to \a filterFunction are invoked from the threads
534 taken from the QThreadPool \a pool. If \a filterFunction returns \c true, a
535 copy of the item is put in the new Sequence. Otherwise, the item will
536 \e not appear in the new Sequence.
537
538 \note This function will block until the iterator reaches the end of the
539 sequence being processed.
540
541 \sa filtered(), {Concurrent Filter and Filter-Reduce}
542*/
543
544/*!
545 \fn template <typename OutputSequence, typename Iterator, typename KeepFunctor> OutputSequence QtConcurrent::blockingFiltered(Iterator begin, Iterator end, KeepFunctor filterFunction)
546
547 Calls \a filterFunction once for each item from \a begin to \a end and
548 returns a new Sequence of kept items. If \a filterFunction returns \c true, a
549 copy of the item is put in the new Sequence. Otherwise, the item will
550 \e not appear in the new Sequence.
551
552 \note This function will block until the iterator reaches the end of the
553 sequence being processed.
554
555 \sa filtered(), {Concurrent Filter and Filter-Reduce}
556*/
557
558/*!
559 \fn template <typename ResultType, typename Sequence, typename KeepFunctor, typename ReduceFunctor> ResultType QtConcurrent::blockingFilteredReduced(QThreadPool *pool, Sequence &&sequence, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions)
560
561 Calls \a filterFunction once for each item in \a sequence.
562 All calls to \a filterFunction are invoked from the threads taken from the QThreadPool \a pool.
563 If \a filterFunction returns \c true for an item, that item is then passed to
564 \a reduceFunction. In other words, the return value is the result of
565 \a reduceFunction for each item where \a filterFunction returns \c true.
566
567 Note that while \a filterFunction is called concurrently, only one thread
568 at a time will call \a reduceFunction. The order in which \a reduceFunction
569 is called is undefined if \a reduceOptions is
570 QtConcurrent::UnorderedReduce. If \a reduceOptions is
571 QtConcurrent::OrderedReduce, \a reduceFunction is called in the order of
572 the original sequence.
573
574 \note This function will block until all items in the sequence have been processed.
575
576 \sa filteredReduced(), {Concurrent Filter and Filter-Reduce}
577*/
578
579/*!
580 \fn template <typename ResultType, typename Sequence, typename KeepFunctor, typename ReduceFunctor> ResultType QtConcurrent::blockingFilteredReduced(Sequence &&sequence, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions)
581
582 Calls \a filterFunction once for each item in \a sequence. If
583 \a filterFunction returns \c true for an item, that item is then passed to
584 \a reduceFunction. In other words, the return value is the result of
585 \a reduceFunction for each item where \a filterFunction returns \c true.
586
587 Note that while \a filterFunction is called concurrently, only one thread
588 at a time will call \a reduceFunction. The order in which \a reduceFunction
589 is called is undefined if \a reduceOptions is
590 QtConcurrent::UnorderedReduce. If \a reduceOptions is
591 QtConcurrent::OrderedReduce, \a reduceFunction is called in the order of
592 the original sequence.
593
594 \note This function will block until all items in the sequence have been processed.
595
596 \sa filteredReduced(), {Concurrent Filter and Filter-Reduce}
597*/
598
599/*!
600 \fn template <typename ResultType, typename Sequence, typename KeepFunctor, typename ReduceFunctor, typename InitialValueType> ResultType QtConcurrent::blockingFilteredReduced(QThreadPool *pool, Sequence &&sequence, KeepFunctor filterFunction, ReduceFunctor reduceFunction, InitialValueType &&initialValue, QtConcurrent::ReduceOptions reduceOptions)
601
602 Calls \a filterFunction once for each item in \a sequence.
603 All calls to \a filterFunction are invoked from the threads taken from the QThreadPool \a pool.
604 If \a filterFunction returns \c true for an item, that item is then passed to
605 \a reduceFunction. In other words, the return value is the result of
606 \a reduceFunction for each item where \a filterFunction returns \c true.
607 The result value is initialized to \a initialValue when the function is
608 called, and the first call to \a reduceFunction will operate on
609 this value.
610
611 Note that while \a filterFunction is called concurrently, only one thread
612 at a time will call \a reduceFunction. The order in which \a reduceFunction
613 is called is undefined if \a reduceOptions is
614 QtConcurrent::UnorderedReduce. If \a reduceOptions is
615 QtConcurrent::OrderedReduce, \a reduceFunction is called in the order of
616 the original sequence.
617
618 \note This function will block until all items in the sequence have been processed.
619
620 \sa filteredReduced(), {Concurrent Filter and Filter-Reduce}
621*/
622
623/*!
624 \fn template <typename ResultType, typename Sequence, typename KeepFunctor, typename ReduceFunctor, typename InitialValueType> ResultType QtConcurrent::blockingFilteredReduced(Sequence &&sequence, KeepFunctor filterFunction, ReduceFunctor reduceFunction, InitialValueType &&initialValue, QtConcurrent::ReduceOptions reduceOptions)
625
626 Calls \a filterFunction once for each item in \a sequence. If
627 \a filterFunction returns \c true for an item, that item is then passed to
628 \a reduceFunction. In other words, the return value is the result of
629 \a reduceFunction for each item where \a filterFunction returns \c true.
630 The result value is initialized to \a initialValue when the function is
631 called, and the first call to \a reduceFunction will operate on
632 this value.
633
634 Note that while \a filterFunction is called concurrently, only one thread
635 at a time will call \a reduceFunction. The order in which \a reduceFunction
636 is called is undefined if \a reduceOptions is
637 QtConcurrent::UnorderedReduce. If \a reduceOptions is
638 QtConcurrent::OrderedReduce, \a reduceFunction is called in the order of
639 the original sequence.
640
641 \note This function will block until all items in the sequence have been processed.
642
643 \sa filteredReduced(), {Concurrent Filter and Filter-Reduce}
644*/
645
646/*!
647 \fn template <typename ResultType, typename Iterator, typename KeepFunctor, typename ReduceFunctor> ResultType QtConcurrent::blockingFilteredReduced(QThreadPool *pool, Iterator begin, Iterator end, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions)
648
649 Calls \a filterFunction once for each item from \a begin to \a end.
650 All calls to \a filterFunction are invoked from the threads taken from the QThreadPool \a pool.
651 If \a filterFunction returns \c true for an item, that item is then passed to
652 \a reduceFunction. In other words, the return value is the result of
653 \a reduceFunction for each item where \a filterFunction returns \c true.
654
655 Note that while \a filterFunction is called concurrently, only one thread
656 at a time will call \a reduceFunction. The order in which
657 \a reduceFunction is called is undefined if \a reduceOptions is
658 QtConcurrent::UnorderedReduce. If \a reduceOptions is
659 QtConcurrent::OrderedReduce, the \a reduceFunction is called in the order
660 of the original sequence.
661
662 \note This function will block until the iterator reaches the end of the
663 sequence being processed.
664
665 \sa filteredReduced(), {Concurrent Filter and Filter-Reduce}
666*/
667
668/*!
669 \fn template <typename ResultType, typename Iterator, typename KeepFunctor, typename ReduceFunctor> ResultType QtConcurrent::blockingFilteredReduced(Iterator begin, Iterator end, KeepFunctor filterFunction, ReduceFunctor reduceFunction, QtConcurrent::ReduceOptions reduceOptions)
670
671 Calls \a filterFunction once for each item from \a begin to \a end. If
672 \a filterFunction returns \c true for an item, that item is then passed to
673 \a reduceFunction. In other words, the return value is the result of
674 \a reduceFunction for each item where \a filterFunction returns \c true.
675
676 Note that while \a filterFunction is called concurrently, only one thread
677 at a time will call \a reduceFunction. The order in which
678 \a reduceFunction is called is undefined if \a reduceOptions is
679 QtConcurrent::UnorderedReduce. If \a reduceOptions is
680 QtConcurrent::OrderedReduce, the \a reduceFunction is called in the order
681 of the original sequence.
682
683 \note This function will block until the iterator reaches the end of the
684 sequence being processed.
685
686 \sa filteredReduced(), {Concurrent Filter and Filter-Reduce}
687*/
688
689/*!
690 \fn template <typename ResultType, typename Iterator, typename KeepFunctor, typename ReduceFunctor, typename InitialValueType> ResultType QtConcurrent::blockingFilteredReduced(QThreadPool *pool, Iterator begin, Iterator end, KeepFunctor filterFunction, ReduceFunctor reduceFunction, InitialValueType &&initialValue, QtConcurrent::ReduceOptions reduceOptions)
691
692 Calls \a filterFunction once for each item from \a begin to \a end.
693 All calls to \a filterFunction are invoked from the threads taken from the QThreadPool \a pool.
694 If \a filterFunction returns \c true for an item, that item is then passed to
695 \a reduceFunction. In other words, the return value is the result of
696 \a reduceFunction for each item where \a filterFunction returns \c true.
697 The result value is initialized to \a initialValue when the function is
698 called, and the first call to \a reduceFunction will operate on
699 this value.
700
701 Note that while \a filterFunction is called concurrently, only one thread
702 at a time will call \a reduceFunction. The order in which
703 \a reduceFunction is called is undefined if \a reduceOptions is
704 QtConcurrent::UnorderedReduce. If \a reduceOptions is
705 QtConcurrent::OrderedReduce, the \a reduceFunction is called in the order
706 of the original sequence.
707
708 \note This function will block until the iterator reaches the end of the
709 sequence being processed.
710
711 \sa filteredReduced(), {Concurrent Filter and Filter-Reduce}
712*/
713
714/*!
715 \fn template <typename ResultType, typename Iterator, typename KeepFunctor, typename ReduceFunctor, typename InitialValueType> ResultType QtConcurrent::blockingFilteredReduced(Iterator begin, Iterator end, KeepFunctor filterFunction, ReduceFunctor reduceFunction, InitialValueType &&initialValue, QtConcurrent::ReduceOptions reduceOptions)
716
717 Calls \a filterFunction once for each item from \a begin to \a end. If
718 \a filterFunction returns \c true for an item, that item is then passed to
719 \a reduceFunction. In other words, the return value is the result of
720 \a reduceFunction for each item where \a filterFunction returns \c true.
721 The result value is initialized to \a initialValue when the function is
722 called, and the first call to \a reduceFunction will operate on
723 this value.
724
725 Note that while \a filterFunction is called concurrently, only one thread
726 at a time will call \a reduceFunction. The order in which
727 \a reduceFunction is called is undefined if \a reduceOptions is
728 QtConcurrent::UnorderedReduce. If \a reduceOptions is
729 QtConcurrent::OrderedReduce, the \a reduceFunction is called in the order
730 of the original sequence.
731
732 \note This function will block until the iterator reaches the end of the
733 sequence being processed.
734
735 \sa filteredReduced(), {Concurrent Filter and Filter-Reduce}
736*/
737
738/*!
739 \fn [QtConcurrent-2] ThreadEngineStarter<typename qValueType<Iterator>::value_type> QtConcurrent::startFiltered(QThreadPool *pool, Iterator begin, Iterator end, KeepFunctor functor)
740 \internal
741*/
742
743/*!
744 \fn [QtConcurrent-3] ThreadEngineStarter<typename Sequence::value_type> QtConcurrent::startFiltered(QThreadPool *pool, Sequence &&sequence, KeepFunctor functor)
745 \internal
746*/
747
748/*!
749 \fn [QtConcurrent-4] ThreadEngineStarter<ResultType> QtConcurrent::startFilteredReduced(QThreadPool *pool, Sequence &&sequence, MapFunctor mapFunctor, ReduceFunctor reduceFunctor, ReduceOptions options)
750 \internal
751*/
752
753/*!
754 \fn [QtConcurrent-5] ThreadEngineStarter<ResultType> QtConcurrent::startFilteredReduced(QThreadPool *pool, Iterator begin, Iterator end, MapFunctor mapFunctor, ReduceFunctor reduceFunctor, ReduceOptions options)
755 \internal
756*/
757
758/*!
759 \fn [QtConcurrent-6] ThreadEngineStarter<ResultType> QtConcurrent::startFilteredReduced(QThreadPool *pool, Sequence &&sequence, MapFunctor mapFunctor, ReduceFunctor reduceFunctor, ResultType initialValue, ReduceOptions options)
760 \internal
761*/
762
763/*!
764 \fn [QtConcurrent-7] ThreadEngineStarter<ResultType> QtConcurrent::startFilteredReduced(QThreadPool *pool, Iterator begin, Iterator end, MapFunctor mapFunctor, ReduceFunctor reduceFunctor, ResultType initialValue, ReduceOptions options)
765 \internal
766*/
767