source: trunk/src/corelib/concurrent/qtconcurrentmap.cpp@ 66

Last change on this file since 66 was 2, checked in by Dmitry A. Kuminov, 16 years ago

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 15.3 KB
Line 
1 /****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** Contact: Qt Software Information ([email protected])
5**
6** This file is part of the QtCore module of the Qt Toolkit.
7**
8** $QT_BEGIN_LICENSE:LGPL$
9** Commercial Usage
10** Licensees holding valid Qt Commercial licenses may use this file in
11** accordance with the Qt Commercial License Agreement provided with the
12** Software or, alternatively, in accordance with the terms contained in
13** a written agreement between you and Nokia.
14**
15** GNU Lesser General Public License Usage
16** Alternatively, this file may be used under the terms of the GNU Lesser
17** General Public License version 2.1 as published by the Free Software
18** Foundation and appearing in the file LICENSE.LGPL included in the
19** packaging of this file. Please review the following information to
20** ensure the GNU Lesser General Public License version 2.1 requirements
21** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
22**
23** In addition, as a special exception, Nokia gives you certain
24** additional rights. These rights are described in the Nokia Qt LGPL
25** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
26** package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you are unsure which license is appropriate for your use, please
37** contact the sales department at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \namespace QtConcurrent
44 \since 4.4
45 \brief The QtConcurrent namespace provides high-level APIs that make it
46 possible to write multi-threaded programs without using low-level
47 threading primitives.
48
49 See the \l {threads.html#qtconcurrent-intro}{Qt Concurrent} section in the \l{threads.html}{threading} documentation.
50
51 \ingroup thread
52*/
53
54/*!
55 \namespace QtConcurrent::internal
56 \internal
57
58 \brief The QtConcurrent::internal namespace contains QtConcurrent
59 implementation details.
60
61 \ingroup thread
62*/
63
64/*!
65 \enum QtConcurrent::ReduceOption
66 This enum specifies the order of which results from the map or filter
67 function are passed to the reduce function.
68
69 \value UnorderedReduce Reduction is done in an arbitrary order.
70 \value OrderedReduce Reduction is done in the order of the
71 original sequence.
72 \value SequentialReduce Reduction is done sequentally: only one
73 thread will enter the reduce function at a time. (Parallel reduction
74 might be supported in a future version of Qt Concurrent.)
75*/
76
77/*!
78 \headerfile <QtConcurrentMap>
79 \title Concurrent Map and Map-Reduce
80 \ingroup threading
81
82 \brief The <QtConcurrentMap> header provides concurrent Map and MapReduce.
83
84 These functions are a part of the \l {threads.html#qtconcurrent-intro}{Qt Concurrent} framework.
85
86 The QtConcurrent::map(), QtConcurrent::mapped() and
87 QtConcurrent::mappedReduced() functions run computations in parallel on
88 the items in a sequence such as a QList or a QVector. QtConcurrent::map()
89 modifies a sequence in-place, QtConcurrent::mapped() returns a new
90 sequence containing the modified content, and QtConcurrent::mappedReduced()
91 returns a single result.
92
93 Each of the above functions has a blocking variant that returns
94 the final result instead of a QFuture. You use them in the same
95 way as the asynchronous variants.
96
97 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 7
98
99 Note that the result types above are not QFuture objects, but real result
100 types (in this case, QList<QImage> and QImage).
101
102 \section1 Concurrent Map
103
104 QtConcurrent::mapped() takes an input sequence and a map function. This map
105 function is then called for each item in the sequence, and a new sequence
106 containing the return values from the map function is returned.
107
108 The map function must be of the form:
109
110 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 0
111
112 T and U can be any type (and they can even be the same type), but T must
113 match the type stored in the sequence. The function returns the modified
114 or \e mapped content.
115
116 This example shows how to apply a scale function to all the items
117 in a sequence:
118
119 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 1
120
121 The results of the map are made available through QFuture. See the
122 QFuture and QFutureWatcher documentation for more information on how to
123 use QFuture in your applications.
124
125 If you want to modify a sequence in-place, use QtConcurrent::map(). The
126 map function must then be of the form:
127
128 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 2
129
130 Note that the return value and return type of the map function are not
131 used.
132
133 Using QtConcurrent::map() is similar to using QtConcurrent::mapped():
134
135 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 3
136
137 Since the sequence is modified in place, QtConcurrent::map() does not
138 return any results via QFuture. However, you can still use QFuture and
139 QFutureWatcher to monitor the status of the map.
140
141 \section1 Concurrent Map-Reduce
142
143 QtConcurrent::mappedReduced() is similar to QtConcurrent::mapped(), but
144 instead of returning a sequence with the new results, the results are
145 combined into a single value using a reduce function.
146
147 The reduce function must be of the form:
148
149 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentmap.cpp 4
150
151 T is the type of the final result, U is the return type of the map
152 function. Note that the return value and return type of the reduce
153 function are not used.
154
155 Call QtConcurrent::mappedReduced() like this: