Detailed Description

A QIviPendingReply 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, QIviPendingReply works also in QML and is especially made for this. The data stored in a QIviPendingReply 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 QIviPendingReply 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 qIviRegisterPendingReplyType function.

When a QIviPendingReply 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 QIviPendingReply has succeeded can be determined by the success property.

Writing a function returning a QIviPendingReply

When writing a function returning a QIviPendingReply, it is often needed to do some input validation and return before actual doing something. Without using a QIviPendingReply 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 QIviPendingReply the validation check needs to be fixed to return a valid QIviPendingReply. To make it more convenient to return a failed reply, the QIviPendingReply::createFailedReply() function be used.

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

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

    QIviPendingReply<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 QIviPendingReply 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 QIviPendingReply is marked as successful and the value set to the displayName().

Note: All copies of a QIviPendingReply use implicit sharing. This data is freed once all copies of the pending replies are deleted.

Using functions returning a QIviPendingReply

When using a function which returns a QIviPendingReply, 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 QIviPendingReplyWatcher.

Signals and Slots

In order to keep the memory footprint low, the QIviPendingReply 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 QIviPendingReplyWatcher 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();
QIviPendingReply<QString> reply = displayName(uuid);
if (reply.isResultAvailable()) {
    if (reply.isSuccessfull())
        useDisplayName(reply.value());
    else
        qWarning("getting the displayName failed");
} else {
    connect(reply.watcher(), &QIviPendingReplyWatcher::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.

Note: The QIviPendingReplyWatcher returned is owned by the QIviPendingReply and all its copies. If all copies of the QIviPendingReply get deleted its QIviPendingReplyWatcher gets deleted as well.

For usage in QML see the QML documentation.