Skip to content
Asynchronous promise implementation for iOS.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Classes
Q.xcodeproj
QTests
bin
.gitignore
LICENSE
Q.podspec
README.md

README.md

Q-ios

An asynchronous promise implementation for iOS.

Inspired by the Q asynchronous promise library for node, this library provides a partial implementation of the Promises/A+ spec.

Installation

Install using CocoaPods:

pod 'Q'

Usage

Create a new promise:

#import "Q.h"
...
QPromise *promise = [QPromise new];

Later, resolve the promise with a result value:

id value = @"something";
[promise resolve:value];

Or reject the promise with an error:

NSError *error = [self raiseError];
[promise reject:error];

Promise continuations can be supplied using blocks:

QPromise *promise = [self asynchronousOp];
promise.then((id)^(id result) {
  // Use result.
})
.fail(^(id error) {
  // Handle error.
});

Promises can be chained using blocks:

QPromise *promise = [QPromise new];
promise.then((id)(^id result) {
    return [QPromise resolve:@"a result!"];
});

or by resolving a promise with a promise:

QPromise *promiseA = [QPromise new];
QPromise *promiseB = [QPromise new];

/// ...stuff...

promiseA.resolve( promiseB );

Create a resolved promise:

QPromise *resolved = [QPromise resolve:@"a result!"];

Or create a rejected promise:

QPromise *rejected = [QPromise reject:@"obsolete"];

Multiple promises

Multiple asynchronous operations can be resolved in one go using the all: method:

QPromise *promise1 = [self httpGet:url1];
QPromise *promise2 = [self httpGet:url2];
QPromise *promise3 = [self httpGet:url3];
NSArray *pending = @[ promise1, promise2, promise3 ];

[QPromise all:pending]
.then((id)^(NSArray *results) {
    id result1 = results[1];
    id result2 = results[2];
    id result3 = results[3];
    // Process results...
})
.fail(^(id error) {
    // Process error...
});

The then block will be passed an array containing the result returned by each corresponding promise in the pending array. If any asynchronous operation fails and its promise rejected then the first error is passed to the fail block.

Gotchas

A then block must return a value. If you fail to do this, then XCode will not generate an error or warning when the code is compiled, but the code will crash with a BAD_ACCESS exception when the block returns:

promise.then((id)^(id result) {
  // No return statement here, code will crash!
});

This can be a particularly easy mistake to make when a then block is the final step in a calculation and doesn't generate any particular result; in these cases, the block should return nil.

Status

This project is currently released as beta code; however, it is fairly well tested and has been used in a number of production projects.

You can’t perform that action at this time.