CopperSpice API: QtConcurrentRun Class Reference

A header which supports running functions in separate threads. More...

Detailed Description

These functions are provided to support Concurrent Programming. 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(). 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.

extern void aFunction();

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

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. 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.

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);

Returning Values from the Function

Any return value from the function is available by calling QFuture.

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

If you need to pass arguments use code similar to the following.

extern QString someFunction(const QByteArray &input);
 
QByteArray bytearray = "SomeText";
QFuture<QString> future = QtConcurrent::run(someFunction, bytearray);
 
// ...
 
QString result = future.result();

The QFuture::result() method 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.

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 QByteArray::split() (a const member function) in a separate thread is done like this:

// call 'QList<QByteArray>  QByteArray::split(char sep) const' in a separate thread
 
QByteArray bytearray = "SomeText";
QFuture<QList<QByteArray> > future = QtConcurrent::run(bytearray, &QByteArray::split, ',');
 
// ...
 
QList<QByteArray> 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 a Lambda Expression

If you want to use a filter function which takes more than one argument use a lambda expression. As an example, we will use QString::left(). Since QString::left() is a method it can not be used with QtConcurrent::run() directly. This is because QtConcurrent::run() expects a function which takes no arguments.

int someFunction(int arg1, double arg2);

QFuture<int> value = QtConcurrent::run( [](){ return someFunction(1, 2.0); } );