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

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

Initially imported qt-all-opensource-src-4.5.1 from Trolltech.
File size: 6.2 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 \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 This function is a part of the \l {threads.html#qtconcurrent-intro}{Qt Concurrent} framework.
50
51 The QtConcurrent::run() function runs a function in a separate thread.
52 The return value of the function is made available through the QFuture API.
53
54 \section1 Running a Function in a Separate Thread
55
56 To run a function in another thread, use QtConcurrent::run():
57
58 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 0
59
60 This will run \e aFunction in a separate thread obtained from the default
61 QThreadPool. You can use the QFuture and QFutureWatcher classes to monitor
62 the status of the function.
63
64 \section1 Passing Arguments to the Function
65
66 Passing arguments to the function is done by adding them to the
67 QtConcurrent::run() call immediately after the function name. For example:
68
69 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 1
70
71 A copy of each argument is made at the point where QtConcurrent::run() is
72 called, and these values are passed to the thread when it begins executing
73 the function. Changes made to the arguments after calling
74 QtConcurrent::run() are \e not visible to the thread.
75
76 \section1 Returning Values from the Function
77
78 Any return value from the function is available via QFuture:
79
80 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 2
81
82 As documented above, passing arguments is done like this:
83
84 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 3
85
86 Note that the QFuture::result() function blocks and waits for the result
87 to become available. Use QFutureWatcher to get notification when the
88 function has finished execution and the result is available.
89
90 \section1 Additional API Features
91
92 \section2 Using Member Functions
93
94 QtConcurrent::run() also accepts pointers to member functions. The first
95 argument must be either a const reference or a pointer to an instance of
96 the class. Passing by const reference is useful when calling const member
97 functions; passing by pointer is useful for calling non-const member
98 functions that modify the instance.
99
100 For example, calling QString::split() (a const member function) in a
101 separate thread is done like this:
102
103 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 4
104
105 Calling a non-const member function is done like this:
106
107 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 5
108
109 \section2 Using Bound Function Arguments
110
111 Note that Qt does not provide support for bound functions. This is
112 provided by 3rd party libraries like
113 \l{http://www.boost.org/libs/bind/bind.html}{Boost} or
114 \l{http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2005/n1836.pdf}
115 {C++ TR1 Library Extensions}.
116
117 You can use boost::bind() or std::tr1::bind() to \e bind a number of
118 arguments to a function when called. There are number of reasons for doing
119 this:
120
121 \list
122 \o To call a function that takes more than 5 arguments.
123 \o To simplify calling a function with constant arguments.
124 \o Changing the order of arguments.
125 \endlist
126
127 See the documentation for the relevant functions for details on how to use
128 the bind API.
129
130 Calling a bound function is done like this:
131
132 \snippet doc/src/snippets/code/src_corelib_concurrent_qtconcurrentrun.cpp 6
133*/
134
135/*!
136 \fn QFuture<T> QtConcurrent::run(Function function, ...);
137 \relates <QtConcurrentRun>
138
139 Runs \a function in a separate thread. The thread is taken from the global
140 QThreadPool. Note that the function may not run immediately; the function
141 will only be run when a thread is available.
142
143 T is the same type as the return value of \a function. Non-void return
144 values can be accessed via the QFuture::result() function.
145
146 Note that the QFuture returned by QtConcurrent::run() does not support
147 canceling, pausing, or progress reporting. The QFuture returned can only
148 be used to query for the running/finished status and the return value of
149 the function.
150*/
Note: See TracBrowser for help on using the repository browser.