QIfPendingReply Class

Detailed Description

A QIfPendingReply is a template class for providing asynchronous results. It can be used as a return value for asynchronous functions, similar to QFuture.

In contrast to QFuture, QIfPendingReply works also in QML and is especially made for this. The data stored in a QIfPendingReply is implicitly shared between all copies of this reply object. This keeps the memory and performance footprint low.

The QML API is very similar to JavaScript Promises, at the same time the C++ API provides support for Qt's signals and slots.

The QIfPendingReply holds a result of a specific type. The type needs to have a default constructor and a copy constructor. By default the most Qt basic types are supported. New types can be added by using the qIfRegisterPendingReplyType function.

When a QIfPendingReply is created it does not have a valid result set yet. This can be checked by using the resultAvailable property. A result for a reply can be set by using the setFailed or setSuccess functions. Setting the result with this function can only be done once and cannot be changed later. Whether a QIfPendingReply has succeeded can be determined by the success property.

Writing a function returning a QIfPendingReply

When writing a function returning a QIfPendingReply, it is often needed to do some input validation and return before actual doing something. Without using a QIfPendingReply one would write a function as follows:

QString displayName(const QUuid &id)
{
    if (id.isNull)
        return QString();

    //do something and wait until the result is ready (synchronous)
    asyncAPI.getDisplayName(id);
    asyncAPI.waitForFinished(&displayNameChanged);
    return asyncAPI.displayName();
}

This function is using an asynchronous API e.g. provided by an IPC. getDisplayName(id) starts the task and once a result is ready the displayNameChanged signal is emitted and the actual value can be read using the displayName() function. The provided function is using a waitForFinished() method to actual wait for the signal to be emitted and return the value and make this API synchronous.

When moving this code to using QIfPendingReply the validation check needs to be fixed to return a valid QIfPendingReply. To make it more convenient to return a failed reply, the QIfPendingReply::createFailedReply() function be used.

Rewriting the above function to be fully asynchronous using a QIfPendingReply it would look like this:

QIfPendingReply<QString> displayName(const QUuid &id)
{
    if (id.isNull)
        return QIfPendingReply<QString>::createFailedReply();

    QIfPendingReply<QString> reply
    //connect to the change signal and set the result to the async reply when ready
    connect(asyncAPI, &displayNameChanged, this, [reply, asyncAPI]() mutable {
            reply.setSuccess(asyncAPI.displayName());
    });
    //start getting the name
    asyncAPI.getDisplayName(id);
    return reply;
}

Now a new QIfPendingReply is created right away and passed to the lamda used in the connect statement. The actual task is started afterwards and the reply object is returned. Once the async API emits the displayNameChanged signal the lamda is executed the QIfPendingReply is marked as successful and the value set to the displayName().

Using functions returning a QIfPendingReply

When using a function which returns a QIfPendingReply, the first thing to do is to check whether a result is already available using the isResultAvailable property and act accordingly. Afterwards you can start to connect the signals provided by the QIfPendingReplyWatcher.

Signals and Slots

In order to keep the memory footprint low, the QIfPendingReply doesn't provide signals directly, as it doesn't need to derive from QObject, but uses the Q_GADGET macro instead. To get notified once a result is ready, the QIfPendingReplyWatcher can be used instead. The watcher can be retrieved using the watcher property.

Here an example on how this would work when using the API described above:

QUuid uuid = createUuid();
QIfPendingReply<QString> reply = displayName(uuid);
if (reply.isResultAvailable()) {
    if (reply.isSuccessfull())
        useDisplayName(reply.value());
    else
        qWarning("getting the displayName failed");
} else {
    connect(reply.watcher(), &QIfPendingReplyWatcher::valueChanged, this, [this, reply]() {
        if (reply.isSuccessfull())
            useDisplayName(reply.value());
        else
            qWarning("getting the displayName failed");
    });
}

As described above, the pending reply is checked first for whether a result is already available and if not, the signals from the watcher are used to react to the valueChanged signal.

For usage in QML see the QML documentation.