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