1 /****************************************************************************
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
6 ** This file is part of the QtCore module of the Qt Toolkit.
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 Digia. For licensing terms and
14 ** conditions see http://qt.digia.com/licensing. For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
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 2.1 as published by the Free Software
20 ** Foundation and appearing in the file LICENSE.LGPL included in the
21 ** packaging of this file. Please review the following information to
22 ** ensure the GNU Lesser General Public License version 2.1 requirements
23 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
25 ** In addition, as a special exception, Digia gives you certain additional
26 ** rights. These rights are described in the Digia Qt LGPL Exception
27 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
29 ** GNU General Public License Usage
30 ** Alternatively, this file may be used under the terms of the GNU
31 ** General Public License version 3.0 as published by the Free Software
32 ** Foundation and appearing in the file LICENSE.GPL included in the
33 ** packaging of this file. Please review the following information to
34 ** ensure the GNU General Public License version 3.0 requirements will be
35 ** met: http://www.gnu.org/copyleft/gpl.html.
40 ****************************************************************************/
43 \namespace QtConcurrent
44 \inmodule QtConcurrent
46 \brief The QtConcurrent namespace provides high-level APIs that make it
47 possible to write multi-threaded programs without using low-level
50 See the \l {Concurrent Programming}{Qt Concurrent} chapter in
51 the \l{threads.html}{threading} documentation.
53 \inheaderfile QtConcurrent
58 \enum QtConcurrent::ReduceOption
59 This enum specifies the order of which results from the map or filter
60 function are passed to the reduce function.
62 \value UnorderedReduce Reduction is done in an arbitrary order.
63 \value OrderedReduce Reduction is done in the order of the
65 \value SequentialReduce Reduction is done sequentially: only one
66 thread will enter the reduce function at a time. (Parallel reduction
67 might be supported in a future version of Qt Concurrent.)
71 \headerfile <QtConcurrentMap>
72 \title Concurrent Map and Map-Reduce
75 \brief The <QtConcurrentMap> header provides concurrent Map and MapReduce.
77 These functions are a part of the \l {Concurrent Programming}{Qt Concurrent} framework.
79 The QtConcurrent::map(), QtConcurrent::mapped() and
80 QtConcurrent::mappedReduced() functions run computations in parallel on
81 the items in a sequence such as a QList or a QVector. QtConcurrent::map()
82 modifies a sequence in-place, QtConcurrent::mapped() returns a new
83 sequence containing the modified content, and QtConcurrent::mappedReduced()
84 returns a single result.
86 Each of the above functions has a blocking variant that returns
87 the final result instead of a QFuture. You use them in the same
88 way as the asynchronous variants.
90 \snippet code/src_concurrent_qtconcurrentmap.cpp 7
92 Note that the result types above are not QFuture objects, but real result
93 types (in this case, QList<QImage> and QImage).
95 \section1 Concurrent Map
97 QtConcurrent::mapped() takes an input sequence and a map function. This map
98 function is then called for each item in the sequence, and a new sequence
99 containing the return values from the map function is returned.
101 The map function must be of the form:
103 \snippet code/src_concurrent_qtconcurrentmap.cpp 0
105 T and U can be any type (and they can even be the same type), but T must
106 match the type stored in the sequence. The function returns the modified
107 or \e mapped content.
109 This example shows how to apply a scale function to all the items
112 \snippet code/src_concurrent_qtconcurrentmap.cpp 1
114 The results of the map are made available through QFuture. See the
115 QFuture and QFutureWatcher documentation for more information on how to
116 use QFuture in your applications.
118 If you want to modify a sequence in-place, use QtConcurrent::map(). The
119 map function must then be of the form:
121 \snippet code/src_concurrent_qtconcurrentmap.cpp 2
123 Note that the return value and return type of the map function are not
126 Using QtConcurrent::map() is similar to using QtConcurrent::mapped():
128 \snippet code/src_concurrent_qtconcurrentmap.cpp 3
130 Since the sequence is modified in place, QtConcurrent::map() does not
131 return any results via QFuture. However, you can still use QFuture and
132 QFutureWatcher to monitor the status of the map.
134 \section1 Concurrent Map-Reduce
136 QtConcurrent::mappedReduced() is similar to QtConcurrent::mapped(), but
137 instead of returning a sequence with the new results, the results are
138 combined into a single value using a reduce function.
140 The reduce function must be of the form:
142 \snippet code/src_concurrent_qtconcurrentmap.cpp 4
144 T is the type of the final result, U is the return type of the map
145 function. Note that the return value and return type of the reduce
146 function are not used.
148 Call QtConcurrent::mappedReduced() like this:
150 \snippet code/src_concurrent_qtconcurrentmap.cpp 5
152 The reduce function will be called once for each result returned by the map
153 function, and should merge the \e{intermediate} into the \e{result}
154 variable. QtConcurrent::mappedReduced() guarantees that only one thread
155 will call reduce at a time, so using a mutex to lock the result variable
156 is not necessary. The QtConcurrent::ReduceOptions enum provides a way to
157 control the order in which the reduction is done. If
158 QtConcurrent::UnorderedReduce is used (the default), the order is
159 undefined, while QtConcurrent::OrderedReduce ensures that the reduction
160 is done in the order of the original sequence.
162 \section1 Additional API Features
164 \section2 Using Iterators instead of Sequence
166 Each of the above functions has a variant that takes an iterator range
167 instead of a sequence. You use them in the same way as the sequence
170 \snippet code/src_concurrent_qtconcurrentmap.cpp 6
172 \section2 Blocking Variants
174 Each of the above functions has a blocking variant that returns
175 the final result instead of a QFuture. You use them in the same
176 way as the asynchronous variants.
178 \snippet code/src_concurrent_qtconcurrentmap.cpp 7
180 Note that the result types above are not QFuture objects, but real result
181 types (in this case, QList<QImage> and QImage).
183 \section2 Using Member Functions
185 QtConcurrent::map(), QtConcurrent::mapped(), and
186 QtConcurrent::mappedReduced() accept pointers to member functions.
187 The member function class type must match the type stored in the sequence:
189 \snippet code/src_concurrent_qtconcurrentmap.cpp 8
191 Note that when using QtConcurrent::mappedReduced(), you can mix the use of
192 normal and member functions freely:
194 \snippet code/src_concurrent_qtconcurrentmap.cpp 9
196 \section2 Using Function Objects
198 QtConcurrent::map(), QtConcurrent::mapped(), and
199 QtConcurrent::mappedReduced() accept function objects, which can be used to
200 add state to a function call. The result_type typedef must define the
201 result type of the function call operator:
203 \snippet code/src_concurrent_qtconcurrentmap.cpp 14
205 \section2 Using Bound Function Arguments
207 Note that Qt does not provide support for bound functions. This is
208 provided by 3rd party libraries like
209 \l{http://www.boost.org/libs/bind/bind.html}{Boost} or
210 \l{http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf}{C++
211 TR1 Library Extensions}.
213 If you want to use a map function that takes more than one argument you can
214 use boost::bind() or std::tr1::bind() to transform it onto a function that
217 As an example, we'll use QImage::scaledToWidth():
219 \snippet code/src_concurrent_qtconcurrentmap.cpp 10
221 scaledToWidth takes three arguments (including the "this" pointer) and
222 can't be used with QtConcurrent::mapped() directly, because
223 QtConcurrent::mapped() expects a function that takes one argument. To use
224 QImage::scaledToWidth() with QtConcurrent::mapped() we have to provide a
225 value for the \e{width} and the \e{transformation mode}:
227 \snippet code/src_concurrent_qtconcurrentmap.cpp 11
229 The return value from boost::bind() is a function object (functor) with
230 the following signature:
232 \snippet code/src_concurrent_qtconcurrentmap.cpp 12
234 This matches what QtConcurrent::mapped() expects, and the complete example
237 \snippet code/src_concurrent_qtconcurrentmap.cpp 13
241 \fn QFuture<void> QtConcurrent::map(Sequence &sequence, MapFunction function)
242 \relates <QtConcurrentMap>
244 Calls \a function once for each item in \a sequence. The \a function is
245 passed a reference to the item, so that any modifications done to the item
246 will appear in \a sequence.
250 \fn QFuture<void> QtConcurrent::map(Iterator begin, Iterator end, MapFunction function)
251 \relates <QtConcurrentMap>
253 Calls \a function once for each item from \a begin to \a end. The
254 \a function is passed a reference to the item, so that any modifications
255 done to the item will appear in the sequence which the iterators belong to.
259 \fn QFuture<T> QtConcurrent::mapped(const Sequence &sequence, MapFunction function)
260 \relates <QtConcurrentMap>
262 Calls \a function once for each item in \a sequence and returns a future
263 with each mapped item as a result. You can use QFuture::const_iterator or
264 QFutureIterator to iterate through the results.
268 \fn QFuture<T> QtConcurrent::mapped(ConstIterator begin, ConstIterator end, MapFunction function)
269 \relates <QtConcurrentMap>
271 Calls \a function once for each item from \a begin to \a end and returns a
272 future with each mapped item as a result. You can use
273 QFuture::const_iterator or QFutureIterator to iterate through the results.
277 \fn QFuture<T> QtConcurrent::mappedReduced(const Sequence &sequence,
278 MapFunction mapFunction, ReduceFunction reduceFunction,
279 QtConcurrent::ReduceOptions reduceOptions)
281 \relates <QtConcurrentMap>
283 Calls \a mapFunction once for each item in \a sequence. The return value of
284 each \a mapFunction is passed to \a reduceFunction.
286 Note that while \a mapFunction is called concurrently, only one thread at a
287 time will call \a reduceFunction. The order in which \a reduceFunction is
288 called is determined by \a reduceOptions.
292 \fn QFuture<T> QtConcurrent::mappedReduced(ConstIterator begin,
293 ConstIterator end, MapFunction mapFunction, ReduceFunction reduceFunction,
294 QtConcurrent::ReduceOptions reduceOptions)
296 \relates <QtConcurrentMap>
298 Calls \a mapFunction once for each item from \a begin to \a end. The return
299 value of each \a mapFunction is passed to \a reduceFunction.
301 Note that while \a mapFunction is called concurrently, only one thread at a
302 time will call \a reduceFunction. By default, the order in which
303 \a reduceFunction is called is undefined.
305 \note QtConcurrent::OrderedReduce results in the ordered reduction.
309 \fn void QtConcurrent::blockingMap(Sequence &sequence, MapFunction function)
311 Calls \a function once for each item in \a sequence. The \a function is
312 passed a reference to the item, so that any modifications done to the item
313 will appear in \a sequence.
315 \note This function will block until all items in the sequence have been processed.
321 \fn void QtConcurrent::blockingMap(Iterator begin, Iterator end, MapFunction function)
323 Calls \a function once for each item from \a begin to \a end. The
324 \a function is passed a reference to the item, so that any modifications
325 done to the item will appear in the sequence which the iterators belong to.
327 \note This function will block until the iterator reaches the end of the
328 sequence being processed.
334 \fn T QtConcurrent::blockingMapped(const Sequence &sequence, MapFunction function)
336 Calls \a function once for each item in \a sequence and returns a Sequence containing
337 the results. The type of the results will match the type returned my the MapFunction.
339 \note This function will block until all items in the sequence have been processed.
345 \fn T QtConcurrent::blockingMapped(ConstIterator begin, ConstIterator end, MapFunction function)
347 Calls \a function once for each item from \a begin to \a end and returns a
348 container with the results. Specify the type of container as the a template
352 QList<int> ints = QtConcurrent::blockingMapped<QList<int> >(beginIterator, endIterator, fn);
355 \note This function will block until the iterator reaches the end of the
356 sequence being processed.
362 \fn T QtConcurrent::blockingMappedReduced(const Sequence &sequence, MapFunction mapFunction, ReduceFunction reduceFunction, QtConcurrent::ReduceOptions reduceOptions)
364 \relates <QtConcurrentMap>
366 Calls \a mapFunction once for each item in \a sequence. The return value of
367 each \a mapFunction is passed to \a reduceFunction.
369 Note that while \a mapFunction is called concurrently, only one thread at a
370 time will call \a reduceFunction. The order in which \a reduceFunction is
371 called is determined by \a reduceOptions.
373 \note This function will block until all items in the sequence have been processed.
379 \fn T QtConcurrent::blockingMappedReduced(ConstIterator begin, ConstIterator end, MapFunction mapFunction, ReduceFunction reduceFunction, QtConcurrent::ReduceOptions reduceOptions)
381 \relates <QtConcurrentMap>
383 Calls \a mapFunction once for each item from \a begin to \a end. The return
384 value of each \a mapFunction is passed to \a reduceFunction.
386 Note that while \a mapFunction is called concurrently, only one thread at a
387 time will call \a reduceFunction. The order in which \a reduceFunction is
390 \note This function will block until the iterator reaches the end of the
391 sequence being processed.
393 \sa blockingMappedReduced()