Qt 4.4: <QtConcurrentRun> - Asynchronous Run

|  | Home · All Classes · Main Classes · Grouped Classes · Modules · Functions |

# <QtConcurrentRun> - Asynchronous Run

### Functions

- QFuture<T> run ( Function function, ... )

This function is a part of the Qt Concurrent framework.

The QtConcurrent::run() function runs a function in a separate thread. The return value of the function is made available through the QFuture API.

### Running a Function in a Separate Thread

To run a function in another thread, use QtConcurrent::run():

         extern void aFunction();
         QFuture<void> future = QtConcurrent::run(aFunction);

This will run aFunction in a separate thread obtained from the default QThreadPool. You can use the QFuture and QFutureWatcher classes to monitor the status of the function.

### Passing Arguments to the Function

Passing arguments to the function is done by adding them to the QtConcurrent::run() call immediately after the function name. For example:

         extern void aFunctionWithArguments(int arg1, double arg2, const QString &string);

         int integer = ...;
         double floatingPoint = ...;
         QString string = ...;

         QFuture<void> future = QtConcurrent::run(aFunctionWithArguments, integer, floatingPoint, string);

A copy of each argument is made at the point where QtConcurrent::run() is called, and these values are passed to the thread when it begins executing the function. Changes made to the arguments after calling QtConcurrent::run() are not visible to the thread.

### Returning Values from the Function

Any return value from the function is available via QFuture:

         extern QString functionReturningAString();
         QFuture<QString> future = QtConcurrent::run(functionReturningAString);
         ...
         QString result = future.result();

As documented above, passing arguments is done like this:

         extern QString someFunction(const QByteArray &input);

         QByteArray bytearray = ...;

         QFuture<QString> future = QtConcurrent::run(someFunction, bytearray);
         ...
         QString result = future.result();

Note that the QFuture::result() function blocks and waits for the result to become available. Use QFutureWatcher to get notification when the function has finished execution and the result is available.

### Additional API Features

#### Using Member Functions

QtConcurrent::run() also accepts pointers to member functions. The first argument must be either a const reference or a pointer to an instance of the class. Passing by const reference is useful when calling const member functions; passing by pointer is useful for calling non-const member functions that modify the instance.

For example, calling QString::split() (a const member function) in a separate thread is done like this:

         // call 'QStringList QString::split(const QString &sep, SplitBehavior behavior, Qt::CaseSensitivity cs) const' in a separate thread
         QString string = ...;
         QFuture<QStringList> future = QtConcurrent::run(string, &QString::split, QString(", "), QString::KeepEmptyParts, Qt::CaseSensitive);
         ...
         QStringList result = future.result();

Calling a non-const member function is done like this:

         // call 'void QImage::invertPixels(InvertMode mode)' in a separate thread
         QImage image = ...;
         QFuture<void> future = QtConcurrent::run(image, &QImage::invertPixels, QImage::InvertRgba);
         ...
         future.waitForFinished();
         // At this point, the pixels in 'image' have been inverted

#### Using Bound Function Arguments

Note that Qt does not provide support for bound functions. This is provided by 3rd party libraries like Boost or C++ TR1 Library Extensions.

You can use boost::bind() or std::tr1::bind() to bind a number of arguments to a function when called. There are number of reasons for doing this:

- To call a function that takes more than 5 arguments.
- To simplify calling a function with constant arguments.
- Changing the order of arguments.

See the documentation for the relevant functions for details on how to use the bind API.

Calling a bound function is done like this:

         void someFunction(int arg1, double arg2);
         QFuture<void> future = QtConcurrent::run(boost::bind(someFunction, 1, 2.0));
         ...

## Function Documentation

### QFuture<T> QtConcurrent::run ( Function function, ... )

Runs function in a separate thread. The thread is taken from the global QThreadPool. Note that the function may not run immediately; the function will only be run when a thread is available.

T is the same type as the return value of function. Non-void return values can be accessed via the QFuture::result() function.

Note that the QFuture returned by QtConcurrent::run() does not support canceling, pausing, or progress reporting. The QFuture returned can only be used to query for the running/finished status and the return value of the function.