Structures

DelayedPromise is like a Promise but it doesn’t invoke its callback until the .promise variable is accessed.

The purpose of DelayedPromise is to allow functions to return calculations that aren’t performed if they’re not needed.

Example:

func getUserInfo() -> (name: String, avatar: DelayedPromise<UIImage,Error>) {
    …
}

let (name, avatar) = getUserInfo()
nameLabel.text = name
avatar.promise.then { [weak self] (image) in
    self?.imageView.image = image
}

A Promise is a construct that will eventually hold a value or error, and can invoke callbacks when that happens.

Example usage:

Promise(on: .utility) { resolver in
    let value = try someLongComputation()
    resolver.fulfill(with: value)
}.then(on: main) { value in
    self.updateUI(with: value)
}.catch(on: .main) { error in
    self.handleError(error)
}

Promises can also be cancelled. With a Promise object you can invoke .requestCancel(), which is merely advisory; the promise does not have to actually implement cancellation and may resolve anyway. But if a promise does implement cancellation, it can then call resolver.cancel(). Note that even if the promise supports cancellation, calling .requestCancel() on an unresolved promise does not guarantee that it will cancel, as the promise may be in the process of resolving when that method is invoked. Make sure to use the invalidation token support if you need to ensure your registered callbacks aren’t invoked past a certain point.

A type that can be used to cancel a promise without holding onto the full promise.

In particular, this acts like a weak reference, allowing for cancelling the promise without creating a retain cycle. Promise retain cycles normally break themselves anyway when the promise is resolved, but a misbehaving promise body may drop the resolver without ever resolving the promise. If the Promise has no more references to it this automatically cancels the promise, but a retain cycle prevents this.

This is returned from Promise.cancellable.

An invalidation token that can be used to cancel callbacks registered to a Promise.

A Promise adapter that automatically applies a PromiseInvalidationToken.

This exposes the same methods as Promise but it always passes a given PromiseInvalidationToken to the underlying promise.

A TokenPromise is created with the method Promise.withToken(_:). The wrapped Promise can be accessed with the .inner property.

Example

methodReturningPromise()
    .withToken(promiseToken)
    .then({ (value) in
        // handle value
    }).catch({ (error) in
        // handle error
    })