Qt Signals

QtPromise supports creating promises that are resolved or rejected by regular Qt signals (opens new window).

IMPORTANT

A promise connected to a signal will be resolved (fulfilled or rejected) only one time, no matter if the signals are emitted multiple times. Internally, the promise is disconnected from all signals as soon as one signal is emitted.

Resolve Signal

The QtPromise::connect() helper allows to create a promise resolved from a single signal:

// [signal] Object::finished(const QByteArray&)
auto output = QtPromise::connect(obj, &Object::finished);

// output type: QPromise<QByteArray>
output.then([](const QByteArray& data) {
    // {...}
});

If the signal doesn't provide any argument, a QPromise<void> is returned:

// [signal] Object::done()
auto output = QtPromise::connect(obj, &Object::done);

// output type: QPromise<void>
output.then([]() {
    // {...}
});

NOTE

QtPromise currently only supports single argument signals, which means that only the first argument is used to fulfill or reject the connected promise, other arguments being ignored.

Reject Signal

The QtPromise::connect() helper also allows to reject the promise from another signal:

// [signal] Object::finished(const QByteArray& data)
// [signal] Object::error(ObjectError error)
auto output = QtPromise::connect(obj, &Object::finished, &Object::error);

// output type: QPromise<QByteArray>
output.then([](const QByteArray& data) {
    // {...}
}).fail([](const ObjectError& error) {
    // {...}
});

If the rejection signal doesn't provide any argument, the promise will be rejected with QPromiseUndefinedException, for example:

// [signal] Object::finished()
// [signal] Object::error()
auto output = QtPromise::connect(obj, &Object::finished, &Object::error);

// output type: QPromise<QByteArray>
output.then([]() {
    // {...}
}).fail([](const QPromiseUndefinedException& error) {
    // {...}
});

A third variant allows to connect the resolve and reject signals from different objects:

// [signal] ObjectA::finished(const QByteArray& data)
// [signal] ObjectB::error(ObjectBError error)
auto output = QtPromise::connect(objA, &ObjectA::finished, objB, &ObjectB::error);

// output type: QPromise<QByteArray>
output.then([](const QByteArray& data) {
    // {...}
}).fail([](const ObjectBError& error) {
    // {...}
});

Additionally to the rejection signal, promises created using QtPromise::connect() are automatically rejected with QPromiseContextException if the sender is destroyed before fulfilling the promise.

See QtPromise::connect() for more details.