Futures is a cross-platform framework for simplifying asynchronous programming, written in Swift. It's lightweight, fast, and easy to understand.
- Ubuntu 14.04
- macOS 10.9
- tvOS 9.0
- iOS 8.0
- watchOS 2.0
Fundamentally, Futures is a very simple framework, that consists of two types:
Promise
, a single assignment container producing aFuture
Future
, a read-only container resolving into either a value, or an error
In many promise frameworks, a promise is undistinguished from a future. This introduces mutability of a promise that gets passed around. In Futures, a Future
is the observable value while a Promise
is the function that sets the value.
Futures are observed, by default, on a single concurrent dispatch queue. This queue can be modified by assigning a different queue to DispatchQueue.futures
. You can also specify a queue of your choice to each callback added to a future .
A future is regarded as:
resolved
, if its value is setfulfilled
, if the value is set, and successfulrejected
, if the value is set, and a failure (error)
When a function returns a Future<Value>
, you can either decide to observe it directly, or continue with more asynchronous tasks. For observing, you use:
whenResolved
, if you're interested in both a value and a rejection errorwhenFulfilled
, if you only care about the valueswhenRejected
, if you only care about the error
If you have more asynchronous work to do based on the result of the first future, you can use
flatMap()
, to execute another future based on the result of the current oneflatMapIfRejected()
, to recover from a potential error resulting from the current futureflatMapThrowing()
, to transform the fulfilled value of the current future or return a rejected futuremap()
, to transform the fulfilled value of the current futurerecover()
,to transform a rejected future into a fulfilled futurealways()
, to execute aVoid
returning closure regardless of whether the current future is rejected or resolvedand()
, to combine the result of two futures into a single tupleFuture<T>.reduce()
, to combine the result of multiple futures into a single future
Note that you can specify an observation dispatch queue for all these functions. For instance, you can use flatMap(on: .main)
, or .map(on: .global())
. By default, the queue is DispatchQueue.futures
.
As a simple example, this is how some code may look:
let future = loadNetworkResource(
from: URL("http://someHost/resource")!
).flatMapThrowing { data in
try jsonDecoder.decode(SomeType.self, from: data)
}.always {
someFunctionToExecuteRegardless()
}
future.whenFulfilled(on: .main) { someType in
// Success
}
future.whenRejected(on: .main) { error in
// Error
}
To create your functions returning a Future<T>
, you create a new pending promise, and resolve it when appropriate.
func performAsynchronousWork() -> Future<String> {
let promise = Promise<String>()
DispatchQueue.global().async {
promise.fulfill(someString)
// If error
promise.reject(error)
}
return promise.future
}
You can also use shorthands.
promise {
try jsonDecoder.decode(SomeType.self, from: data)
} // Future<SomeType>
Or shorthands which you can return from asynchronously.
promise(String.self) { completion in
/// ... on success ...
completion(.fulfill("Some string"))
/// ... if error ...
completion(.reject(anError))
} // Future<String>
The complete documentation can be found here.
Futures can be added to your project either using Carthage or Swift package manager.
If you want to depend on Futures in your project, it's as simple as adding a dependencies
 clause to your Package.swift
:
dependencies: [
.package(url: "https://github.com/davidask/Futures.git", from: "1.6.0")
]
Or, add a dependency in your Cartfile
:
github "davidask/Futures"
More details on using Carthage can be found here.
Lastly, import the module in your Swift files
import Futures
Please feel welcome contributing to Futures, check the LICENSE
file for more info.
David Ask