5.6 KiB

Raw Blame History

Futures

You may have noticed some APIs in Vapor expect or return a Future<T> type. If this is your first time hearing about futures, they might seem a little confusing at first. But don't worry, Vapor makes them easy to use.

Promises and Futures are two strongly related types. Every promise has a future. A promise is a write-only entity that has the ability to complete (or fail) it's Future counterpart.

Futures are a read-only entity that can have a successful or error case. Successful cases are called the "Expectation".

Futures can be used to register callbacks to, which will always executed in the order of registration. Promises can only be completed once. If a promise is completed more than once the input will be ignored.

Basics

Creating a promise is when the result is returned in the future at an unknown time. For the sake of demonstration, however, the promise will be completed at a predefined point in time and execution.

Within the .do block you may not throw an error or return a result.

let promise = Promise<String>()
let future = promise.future // Future<String>

future.do { string in
    print(string)
}

promise.complete("Hello")

The above code prints "Hello" in the console.

Errors

When running the above code, you may have noticed a warning pop up. This is because the .do block only handles successful completions. If we were to replace the completion with the following code the .do block would never get run:

struct MyError: Error {}

promise.fail(MyError())

Instead, a .catch block will be triggered.

future.do { string in
    print(string)
}.catch { error in
    print("Error '\(error)' occurred")
}

In this scenario the test "Error 'MyError' occurred" will appear.

Within the .catch block you may not throw an error or return a result.

Basic Transformations

Transformations are one of the more critical parts of Vapor 3's future system. They assist in reducing the complexity of futures and keep code isolated and readable. You can use the .map function to transform the future expectation to another future of the same or a different type. You need to explicitly state which type will be returned in the mapping closure.

The mapping closure(s) will only be executed if an expectation has been received in the previous step. If at any point a transformation function throws an error, execution stops there and the .catch block will be executed.

If the promise that was mapped failed to begin with, the .catch block will also be executed without triggering any mapping closures.

let promise = Promise<Int>()

promise.future.do { int in
    print(int)
}.map(to: Int.self) { int in
    return int + 4
}.map(to: String.self) { int in
    return int.description
}.do { string in
    print(string)
}.catch { error in
    print("Error '\(error)' occurred")
}

promise.complete(3)

The above code will print the inputted integer. Then map the input to (integer + 4) == 7. Then the textual representation of the integer is returned as a String which will be printed.

This results in the following console output:

3
7

Recursive futures

In the above map function we returned a new result synchronously. In some situations, however, you'll need to dispatch another asynchronous call based on the result of a previous call.

First, let's see how this would work out using map by exaggerating synchronous code as if it were an asynchronous call.

!!! warning Do not use this implementation, use the next one instead. This is an unnecessarily complicated way of nesting futures.

let promise = Promise<Int>()

promise.map(to: Future<Int>.self) { int in
    return Future(int + 4)
}.map(to: Future<Future<String>>.self) { futureInt in
    return futureInt.map(to: Future<String.self>) { int in
        return Future(int.description)
    }
}.do { doubleFutureString in // Future<Future<String>>
    doubleFutureString.do { futureString in // Future<String>
      futureString.do { string in
          print(string)
      }.catch { error in
          print("Error '\(error)' occurred")
      }
    }.catch { error in
        print("Error '\(error)' occurred")
    }
}.catch { error in
    print("Error '\(error)' occurred")
}

promise.complete(3)

To flatten this asynchronous recursion, instead, we recommend using flatMap. The type supplied in the to: argument is implied to be wrapped in a Future<>.

let promise = Promise<Int>()

promise.flatMap(to: Int.self) { int in
    return Future<Int>(int + 4)
}.flatMap(to: String.self) { int in
    return Future(int.description)
}.do { string in
    print(string)
}.catch { error in
    print("Error '\(error)' occurred")
}

promise.complete(3)

Always

Sometimes you want to always execute a function as part of the cleanup phase. You can use the .always block to execute a block of code after the future has been successfully executed (and mapped if applicable) or when an error occurs. Please do consider that always also will be executed in the order in which it has been registered, like all other closures.

var i = 0
        
let promise = Promise<Int>()
let future = promise.future // Future<Int>

future.do { int in
    i += int * 3
}.do { int in
    i += (int - 1)
}.always {
    print(i)
    i = 0
}.catch { _ in
    i = -1
}

At the end of the above function, i will always be 0. If the promise is completed with the successful result i, the number "11" will be printed. On error, "-1" will be printed.

Signals

Signals, or Future<Void> is a Future that can contain either an Error or Void (the Expectation). Future<Void> is often used to indicate the successful or unsuccessful completion of a task.

5.6 KiB Raw Blame History