Futures

Swift framework for Promises and Futures focusing on a small and simple API.

Goals

• I needed both Promises and Futures for a project at work and I wanted to write my own library.
• Use Swift to do something useful.
• Write the simplest possible Futures and Promises library that I could, both in implementation, and API.
• Expand API only as necessary. If you use this library and would like a new feature, let me know!
• Use generics and other techniques to improve upon my old implementation.
• Swift backwards compatibility is not particularly important to me. I will update to the latest Swift version as soon as I have time. If you use this library and aren’t a fan of this policy, let me know.

Usage

First, drop the following line in your Podfile

pod 'Futures', '~> 2.0'

Then, just import Futures and go!

Examples

Using a future to calculate an expensive value:

let f = Future<Int>() { _ in
    .Success(Box(fibonacci(16)))
}

f.onSuccess() {
    println($0) // 987
}

Note: The use of the Box class to return successful results is due to a (seemingly temporary) shortcoming in Swift right now where all of an enum’s associated values must be of a known size at compile time.

Shorthand:

future(fibonacci(16)).onSuccess() {
    println($0) // 987
}

Handling errors:

Future<Int>() { _ in
    .Error(NSError())
}.onSuccess() { value in
    // handle value
}.onError() { error in
    // handle error
}

Blocking indefinitely for a value:

if let fib16 = future(fibonacci(16)).successValue {
    println(fib16) // 987
}

Blocking temporarily for a value:

if let fib16 = future(fibonacci(16)).valueWithTimeout(10)?.successValue {
    println(fib16) // 987
}

Shorthand for associating Futures with a queue.

let queue = dispatch_queue_create("Test", DISPATCH_QUEUE_SERIAL)
// somewhere else
let f = queue.createFuture(fibonacci(16))

FutureCache

FutureCache is a simple and useful way to initialize and cache expensive values.

let futureCache = FutureCache<Int>()
futureCache.add("fib16", future: future(fibonacci(16)))
// later...
let expensiveResult = futureCache.valueForKey("fib16")!

Version History

1.0

Initial release.

1.0.1

Adds some missing documentation.

1.1

Adds FutureCache.

1.1.1

Adds missing doc strings for onSuccess and onError methods.

1.2

Updates to Swift 1.2. This kills the @autoclosure. :-(

1.2.1

Fixes a possible dead lock if you used the .state property in a work/onSuccess/onError closure of a Promise or Deref.

1.3

Adds extensions to dispatch_queue_t for creating associated futures.

2.0

• Further unifies Promise and Future’s implementation by turning FutureResult into a DerefResult. .value now returns a DerefValue<T>. .successValue has been added as a convenience to get the old behavior of .value.
• Futures now support cancelation. Future workBlocks are now passed an isCanceled block which the workBlock may check periodically to stop expensive work early. This works much like a custom NSOperation subclass might. Simple shorthand still exists for Futures that are known to only succeed and which do not care about cancellation.
• FutureCache has been updated (and simplified) appropriately given the previous two bullet points.

2.0.1

• Adds @autoclosure(escaping) shorthand for futures. Hooray! Requires Xcode 6.3 beta 2.

2.0.2

• Updates queue helpers for @autoclosure(escaping).