source: trunk/src/corelib/concurrent/qtconcurrentrun.cpp@ 991

Last change on this file since 991 was 846, checked in by Dmitry A. Kuminov, 14 years ago

trunk: Merged in qt 4.7.2 sources from branches/vendor/nokia/qt.
File size: 6.2 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the QtCore module of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and Nokia.
15**
16** GNU Lesser General Public License Usage
17** Alternatively, this file may be used under the terms of the GNU Lesser
18** General Public License version 2.1 as published by the Free Software
19** Foundation and appearing in the file LICENSE.LGPL included in the
20** packaging of this file. Please review the following information to
21** ensure the GNU Lesser General Public License version 2.1 requirements
22** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23**
24** In addition, as a special exception, Nokia gives you certain additional
25** rights. These rights are described in the Nokia Qt LGPL Exception
26** version 1.1, included in the file LGPL_EXCEPTION.txt in this 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 have questions regarding the use of this file, please contact
37** Nokia at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \headerfile <QtConcurrentRun>
44 \title Asynchronous Run
45
46 \brief The <QtConcurrentRun> header provides a way to run a function in a
47 separate thread.
48
49 \ingroup thread
50
51 This function is a part of the \l {Concurrent Programming}{Qt Concurrent} framework.
52
53 The QtConcurrent::run() function runs a function in a separate thread.
54 The return value of the function is made available through the QFuture API.
55
56 \section1 Running a Function in a Separate Thread
57
58 To run a function in another thread, use QtConcurrent::run():
59
60 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 0
61
62 This will run \e aFunction in a separate thread obtained from the default
63 QThreadPool. You can use the QFuture and QFutureWatcher classes to monitor
64 the status of the function.
65
66 \section1 Passing Arguments to the Function
67
68 Passing arguments to the function is done by adding them to the
69 QtConcurrent::run() call immediately after the function name. For example:
70
71 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 1
72
73 A copy of each argument is made at the point where QtConcurrent::run() is
74 called, and these values are passed to the thread when it begins executing
75 the function. Changes made to the arguments after calling
76 QtConcurrent::run() are \e not visible to the thread.
77
78 \section1 Returning Values from the Function
79
80 Any return value from the function is available via QFuture:
81
82 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 2
83
84 As documented above, passing arguments is done like this:
85
86 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 3
87
88 Note that the QFuture::result() function blocks and waits for the result
89 to become available. Use QFutureWatcher to get notification when the
90 function has finished execution and the result is available.
91
92 \section1 Additional API Features
93
94 \section2 Using Member Functions
95
96 QtConcurrent::run() also accepts pointers to member functions. The first
97 argument must be either a const reference or a pointer to an instance of
98 the class. Passing by const reference is useful when calling const member
99 functions; passing by pointer is useful for calling non-const member
100 functions that modify the instance.
101
102 For example, calling QByteArray::split() (a const member function) in a
103 separate thread is done like this:
104
105 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 4
106
107 Calling a non-const member function is done like this:
108
109 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 5
110
111 \section2 Using Bound Function Arguments
112
113 Note that Qt does not provide support for bound functions. This is
114 provided by 3rd party libraries like
115 \l{http://www.boost.org/libs/bind/bind.html}{Boost} or
116 \l{http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf}
117 {C++ TR1 Library Extensions}.
118
119 You can use boost::bind() or std::tr1::bind() to \e bind a number of
120 arguments to a function when called. There are number of reasons for doing
121 this:
122
123 \list
124 \o To call a function that takes more than 5 arguments.
125 \o To simplify calling a function with constant arguments.
126 \o Changing the order of arguments.
127 \endlist
128
129 See the documentation for the relevant functions for details on how to use
130 the bind API.
131
132 Calling a bound function is done like this:
133
134 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 6
135*/
136
137/*!
138 \fn QFuture<T> QtConcurrent::run(Function function, ...);
139 \relates <QtConcurrentRun>
140
141 Runs \a function in a separate thread. The thread is taken from the global
142 QThreadPool. Note that the function may not run immediately; the function
143 will only be run when a thread is available.
144
145 T is the same type as the return value of \a function. Non-void return
146 values can be accessed via the QFuture::result() function.
147
148 Note that the QFuture returned by QtConcurrent::run() does not support
149 canceling, pausing, or progress reporting. The QFuture returned can only
150 be used to query for the running/finished status and the return value of
151 the function.
152*/
Note: See TracBrowser for help on using the repository browser.