- Qt 6.12
- Qt TaskTree
- C++ Classes
- QThreadFunction
- Qt 6.12.0 Reference Documentation

# QtTaskTree::QThreadFunction Class

template <typename ResultType> class QtTaskTree::QThreadFunction

A class template controlling the execution of a function in a separate thread via QtConcurrent::run(). More...

Header: | `#include <qthreadfunctiontask.h>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS TaskTree)` `target_link_libraries(mytarget PRIVATE Qt6::TaskTree)`
qmake: | `QT += tasktree`
Since: | Qt 6.11
Inherits: | QtTaskTree::QThreadFunctionBase
Status: | Technology preview

This class is in technology preview and is subject to change.

- List of all members, including inherited members

Note: All functions in this class are reentrant.

## Public Functions

| QThreadFunction(QObject *parent = nullptr)
virtual | ~QThreadFunction() override
QFuture<ResultType> | future() const
QFutureWatcher<ResultType> * | futureWatcher()
const QFutureWatcher<ResultType> * | futureWatcher() const
bool | isAutoDelayedSync() const
bool | isDone() const
bool | isResultAvailable() const
ResultType | result() const
ResultType | resultAt(int index) const
QList<ResultType> | results() const
void | setAutoDelayedSync(bool on)
void | setThreadFunctionData(Function &&function, Args &&... args)
void | setThreadPool(QThreadPool *pool)
ResultType | takeResult() const
QThreadPool * | threadPool() const

## Detailed Description

A QThreadFunction is a convenient class template, where ResultType specifies the return type of the stored function, that combines a stored function to be called later via QtConcurrent::run() with an internal QFutureWatcher monitoring the function execution. Use QThreadFunctionTask to execute the QThreadFunction inside the QTaskTree recipe.

Set a function with its arguments to be executed in a separate thread using setThreadFunctionData() method.

To report an error from inside the function running in a separate thread, place the `QPromise<ResultType> &promise` argument in that function as the first argument, and cancel the promise's future. Example:

     static void copyFile(QPromise<void> &promise, const QString &source,
                          const QString &destination)
     {
         const QFileInfo fi(source);
         if (!fi.exists()) {
             promise.future().cancel(); // The QThreadFunction finishes with DoneResult::Error
             return;
         }

         // Copy file...
     }

     QThreadFunction<void> task;
     task.setThreadFunctionData(copyFile, "source.txt", "dest.txt");
     task.start();

Use setThreadPool() to execute a function in a desired QThreadPool, otherwise the function will use the global thread pool.

Use setAutoDelayedSync() to switch the automatic delayed synchronization.

To control the function execution, connect to the signals of the associated futureWatcher(). To collect the output data, use result(), resultAt(), or results() getters.

## Member Function Documentation

### `[implicit]` QThreadFunction::QThreadFunction(QObject *parent = nullptr)

Constructs a QThreadFunction with a given parent.

### `[override virtual]` QThreadFunction::~QThreadFunction()

Destroys the QThreadFunction. If the QThreadFunction is not running, no other actions are performed, otherwise the associated future is canceled, and depending on the automatic delayed synchronization the following actions are performed:

Automatic Delayed Synchronization | Action
--- | ---
On | The associated QFuture is stored in the global registry. Use QThreadFunctionBase::syncAll() on application quit to synchronize all futures stored previously in the global registry.
Off | A blocking call to QFuture::waitForFinished() is executed directly.

When the automatic delayed synchronization is on, the cancellation of the future may be intercepted inside the still running function in a separate thread, so that it may finish as soon as possible without completing its job.

Finally, on application quit, QThreadFunctionBase::syncAll() should be called in order to synchronize all the functions still being potentially running in separate threads. The call to QThreadFunctionBase::syncAll() is blocking in case some functions are still finalizing.

Note: When the automatic delayed synchronization is on, the function will still run for a while after the QThreadFunction's destructor is finished, so it's the user responsibility to ensure that all data the function may operate on is still available. If that can't be guaranteed, set the automatic delayed synchronization to off via QThreadFunction::setAutoDelayedSync(false). In this case the QThreadFunction destructor will blocking wait for the function to be finished before deleting the QThreadFunction. Refer to QCustomTask documentation for more information about `Deleter` template parameter.

See also setAutoDelayedSync() and syncAll().

### QFuture<ResultType> QThreadFunction::future() const

Returns the QFuture<ResultType> associated with the function executed in a separate thread.

### QFutureWatcher<ResultType> *QThreadFunction::futureWatcher()

Returns the pointer to the `QFutureWatcher<ResultType>` associated with the function executed in a separate thread. The lifetime of the returned watcher is bound to the QThreadFunction instance.

Use this function if you need more control over the future execution, for example, to connect to the progress signals of the returned watcher.

### const QFutureWatcher<ResultType> *QThreadFunction::futureWatcher() const

Returns the `const` pointer to the `QFutureWatcher<ResultType>` associated with the function executed in a separate thread.

This is an overloaded function.

### bool QThreadFunction::isAutoDelayedSync() const

Returns whether the automatic delayed synchronization is on.

See also syncAll() and setAutoDelayedSync().

### bool QThreadFunction::isDone() const

Returns whether the function execution is finished.

### bool QThreadFunction::isResultAvailable() const

Returns whether the result is ready.

See also result().

### ResultType QThreadFunction::result() const

Returns the ResultType reported by the function executed in a separate thread.

Note: Ensure the result is ready by calling isResultAvailable(), otherwise the call to result() may block in case the result wasn't reported yet, or even crash in case the function execution finished without reporting any result.

See also QFutureWatcher::result().

### ResultType QThreadFunction::resultAt(int index) const

Returns the ResultType reported by the function executed in a separate thread at index.

See also result() and QFutureWatcher::resultAt().

### QList<ResultType> QThreadFunction::results() const

Returns the list of ResultType reported by the function executed in a separate thread.

See also result(), resultAt(), and QFuture::results().

### void QThreadFunction::setAutoDelayedSync(bool on)

Sets the automatic delayed synchronization to on.

By default, an automatic delayed synchronization is on, meaning the destruction of the running QThreadFunction object won't blocking wait until the function running in separate thread is finished. Instead, the associated QFuture is canceled, and the function is left running until it's finished. The cancellation can be intercepted by the function running in a separate thread via the QPromise argument, so that it may finish early without completing its job. In case the automatic delayed synchronization is on, it's necessary to call QThreadFunctionBase::syncAll() on application quit, in order to synchronize all the possibly running functions in separate threads.

When the automatic delayed synchronization is off, the synchronization happens on QThreadFunction's destruction, what can block the caller thread for considerable amount of time.

The automatic synchronization is used only when QThreadFunction was executed from the main thread.

See also syncAll() and isAutoDelayedSync().

### template <typename Function, typename... Args> void QThreadFunction::setThreadFunctionData(Function &&function, Args &&... args)

Sets the function to be executed with passed args in a separate thread when start() is called.

See also QtConcurrent::run().

### void QThreadFunction::setThreadPool(QThreadPool *pool)

Sets the QThreadPool pool to be used when executing the call. If the passed pool is `nullptr`, the QThreadPool::globalInstance() is used.

See also threadPool().

### ResultType QThreadFunction::takeResult() const

Takes (moves) the ResultType reported by the function executed in a separate thread.

Note: Ensure the result is ready by calling isResultAvailable(), otherwise the call to takeResult() may block in case the result wasn't reported yet, or even crash in case the function execution finished without reporting any result.

See also QFuture::takeResult().

### QThreadPool *QThreadFunction::threadPool() const

Returns the thread pool that is used when executing the call. If `nullptr` is returned, the QThreadPool::globalInstance() is used.

See also setThreadPool().