- Qt 5.15
- Qt Concurrent
- Concurrent Run
- Qt 5.15.19 Reference Documentation

# Concurrent Run

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

This function is a part of the Qt Concurrent framework.

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

To use a dedicated thread pool, you can pass the QThreadPool as the first argument:

     extern void aFunction();
     QThreadPool pool;
     QFuture<void> future = QtConcurrent::run(&pool, 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. 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();

If you don't need the result (for example, because the function returns `void`), using the QThreadPool::start() overload taking a function object is more efficient.

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 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 = "hello world";
     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 Lambda Functions

Calling a lambda function is done like this:

     QFuture<void> future = QtConcurrent::run([=]() {
         // Code in this block will run in another thread
     });
     ...