QConcurrentCall Class

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

    // Copy file...
}

QConcurrentCall<void> task;
task.setConcurrentCallData(copyFile, "source.txt", "dest.txt");
task.start();

Member Function Documentation

[explicit] QConcurrentCall::QConcurrentCall(QObject *parent = nullptr)

Constructs a QConcurrentCall with a given parent.

[override virtual] QConcurrentCall::~QConcurrentCall()

Destroys the QConcurrentCall. If the QConcurrentCall 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:

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, QConcurrentCallBase::syncAll() should be called in order to synchronize all the functions still being potentially running in separate threads. The call to QConcurrentCallBase::syncAll() is blocking in case some functions are still finalizing.

See also setAutoDelayedSync() and syncAll().

[signal] void QConcurrentCall::done(QtTaskTree::DoneResult result)

This signal is emitted just after the execution of the stored function has finished. The passed result indicates whether the function finished with success or an error.

See also start() and isDone().

QFuture<ResultType> QConcurrentCall::future() const

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

bool QConcurrentCall::isAutoDelayedSync() const

Returns whether the automatic delayed synchronization is on.

See also syncAll() and setAutoDelayedSync().

bool QConcurrentCall::isDone() const

Returns whether the function execution is finished.

See also start() and done().

bool QConcurrentCall::isResultAvailable() const

Returns whether the result is ready.

See also result().

[signal] void QConcurrentCall::progressRangeChanged(int minimum, int maximum)

This signal is emitted whenever the progress range of the concurrent call has changed to minimum and maximum.

See also QPromise::setProgressRange() and QFutureWatcher::progressRangeChanged().

[signal] void QConcurrentCall::progressTextChanged(const QString &text)

This signal is emitted when the textual progress of the function executed in a separate thread has changed to text.

See also QPromise::setProgressValueAndText() and QFutureWatcher::progressTextChanged().

[signal] void QConcurrentCall::progressValueChanged(int value)

This signal is emitted when the progress value of the function executed in a separate thread has changed to value.

See also QPromise::setProgressValue() and QFutureWatcher::progressValueChanged().

ResultType QConcurrentCall::result() const

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

See also QFutureWatcher::result().

ResultType QConcurrentCall::resultAt(int index) const

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

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

[signal] void QConcurrentCall::resultReadyAt(int index)

This signal is emitted whenever the function running in a separate thread reported any partial result at index via QPromise::addResult(). To get the result, call resultAt(index);

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

QList<ResultType> QConcurrentCall::results() const

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

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

[signal] void QConcurrentCall::resultsReadyAt(int beginIndex, int endIndex)

This signal is emitted whenever the function running in a separate thread reported any ready results indexed from beginIndex to endIndex. To get the result, call resultAt(index);

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

void QConcurrentCall::setAutoDelayedSync(bool on)

Sets the automatic delayed synchronization to on.

By default, an automatic delayed synchronization is on, meaning the destruction of the running QConcurrentCall 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 QConcurrentCallBase::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 QConcurrentCall's destruction, what can block the caller thread for considerable amount of time.

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

See also syncAll() and isAutoDelayedSync().

template <typename Function, typename... Args> void QConcurrentCall::setConcurrentCallData(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 QConcurrentCall::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().

void QConcurrentCall::start()

Starts the asynchronous invocation of stored function in a separate thread. Connect to done() signal to collect the result reported by the function.

See also setConcurrentCallData() and done().

[signal] void QConcurrentCall::started()

This signal is emitted just after the execution of the stored function has started.

See also done().

ResultType QConcurrentCall::takeResult() const

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

See also QFuture::takeResult().

QThreadPool *QConcurrentCall::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().