Other Functions

The following functions are available globally.

  •  after(seconds: 1.5).then {
     //…
 }

    Note

    cancelling this guarantee will cancel the underlying timer task

    See also

    Cancellation

    Declaration

    Swift

    public func after(seconds: TimeInterval) -> Guarantee<Void>

    Return Value

    A guarantee that resolves after the specified duration.

  • after(.seconds(2)).then {
    //…
}

    Note

    cancelling this guarantee will cancel the underlying timer task

    See also

    Cancellation

    Declaration

    Swift

    public func after(_ interval: DispatchTimeInterval) -> Guarantee<Void>

    Return Value

    A guarantee that resolves after the specified duration.

  • Judicious use of firstly may make chains more readable.

    Compare:

    URLSession.shared.dataTask(url: url1).then {
    URLSession.shared.dataTask(url: url2)
}.then {
    URLSession.shared.dataTask(url: url3)
}

    With:

    firstly {
    URLSession.shared.dataTask(url: url1)
}.then {
    URLSession.shared.dataTask(url: url2)
}.then {
    URLSession.shared.dataTask(url: url3)
}

    Note

    the block you pass executes immediately on the current thread/queue.

    Declaration

    Swift

    public func firstly<U>(execute body: () throws -> U) -> Promise<U.T> where U : Thenable

  • See

    firstly()

    Declaration

    Swift

    public func firstly<T>(execute body: () -> Guarantee<T>) -> Guarantee<T>

  • firstly for cancellable promises.

    Compare:

    let context = URLSession.shared.dataTask(url: url1).cancellize().then {
    URLSession.shared.dataTask(url: url2)
}.then {
    URLSession.shared.dataTask(url: url3)
}.cancelContext

// …

context.cancel()

    With:

    let context = firstly {
    URLSession.shared.dataTask(url: url1)
}.cancellize().then {
    URLSession.shared.dataTask(url: url2)
}.then {
    URLSession.shared.dataTask(url: url3)
}.cancelContext

// …

context.cancel()

    Note

    the block you pass excecutes immediately on the current thread/queue.

    See

    firstly(execute: () -> Thenable)

    Declaration

    Swift

    public func firstly<V>(execute body: () throws -> V) -> CancellablePromise<V.U.T> where V : CancellableThenable

  • Runs the active run-loop until the provided promise resolves.

    This is for debug and is not a generally safe function to use in your applications. We mostly provide it for use in testing environments.

    Still if you like, study how it works (by reading the sources!) and use at your own risk.

    Throws

    An error, should the promise be rejected

    See

    wait()

    Declaration

    Swift

    public func hang<T>(_ promise: Promise<T>) throws -> T

    Return Value

    The value of the resolved promise

  • Runs the active run-loop until the provided promise resolves.

    Simply calls hang directly on the delegate promise, so the behavior is exactly the same with Promise and CancellablePromise.

    Declaration

    Swift

    public func hang<T>(_ promise: CancellablePromise<T>) throws -> T

  • Waits for one promise to resolve

    race(promise1, promise2, promise3).then { winner in
    //…
}

    Warning

    If the first resolution is a rejection, the returned promise is rejected

    Declaration

    Swift

    public func race<U>(_ thenables: U...) -> Promise<U.T> where U : Thenable

    Return Value

    The promise that resolves first

  • Waits for one promise to resolve

    race(promise1, promise2, promise3).then { winner in
    //…
}

    Warning

    If the first resolution is a rejection, the returned promise is rejected

    Remark

    If the provided array is empty the returned promise is rejected with PMKError.badInput

    Declaration

    Swift

    public func race<U>(_ thenables: [U]) -> Promise<U.T> where U : Thenable

    Return Value

    The promise that resolves first

  • Waits for one guarantee to resolve

    race(promise1, promise2, promise3).then { winner in
    //…
}

    Declaration

    Swift

    public func race<T>(_ guarantees: Guarantee<T>...) -> Guarantee<T>

    Return Value

    The guarantee that resolves first

  • Resolves with the first resolving cancellable promise from a set of cancellable promises. Calling cancel on the race promise cancels all pending promises. All promises will be cancelled if any promise rejects.

    let racePromise = race(promise1, promise2, promise3).then { winner in
    //…
}

//…

racePromise.cancel()

    Warning

    If any of the provided promises reject, the returned promise is rejected.

    Warning

    aborts if the array is empty.

    Declaration

    Swift

    public func race<V>(_ thenables: V...) -> CancellablePromise<V.U.T> where V : CancellableThenable

    Return Value

    A new promise that resolves when the first promise in the provided promises resolves.

  • Resolves with the first resolving promise from a set of promises. Calling cancel on the race promise cancels all pending promises. All promises will be cancelled if any promise rejects.

    let racePromise = race(promise1, promise2, promise3).then { winner in
    //…
}

//…

racePromise.cancel()

    Warning

    If any of the provided promises reject, the returned promise is rejected.

    Remark

    Returns promise rejected with PMKError.badInput if empty array provided

    Declaration

    Swift

    public func race<V>(_ thenables: [V]) -> CancellablePromise<V.U.T> where V : CancellableThenable

    Return Value

    A new promise that resolves when the first promise in the provided promises resolves.

  • Waits for one promise to fulfill

    race(fulfilled: [promise1, promise2, promise3]).then { winner in
    //…
}

    Warning

    Skips all rejected promises.

    Remark

    If the provided array is empty, the returned promise is rejected with PMKError.badInput. If there are no fulfilled promises, the returned promise is rejected with PMKError.noWinner.

    Declaration

    Swift

    public func race<U>(fulfilled thenables: [U]) -> Promise<U.T> where U : Thenable

    Return Value

    The promise that was fulfilled first.

  • Returns a promise that can be used to set a timeout for race.

    let promise1, promise2: Promise<Void>
race(promise1, promise2, timeout(seconds: 1.0)).done { winner in
    //…
}.catch(policy: .allErrors) {
    // Rejects with `PMKError.timedOut` if the timeout is exceeded before either `promise1` or
    // `promise2` succeeds.
}

    When used with cancellable promises, all promises will be cancelled if the timeout is exceeded or any promise rejects:

    let promise1, promise2: CancellablePromise<Void>
race(promise1, promise2, cancellize(timeout(seconds: 1.0))).done { winner in
    //…
}

    Declaration

    Swift

    public func timeout(seconds: TimeInterval) -> Promise<Void>

  • Wait for all promises in a set to fulfill.

    For example:

    when(fulfilled: promise1, promise2).then { results in
    //…
}.catch { error in
    switch error {
    case URLError.notConnectedToInternet:
        //…
    case CLError.denied:
        //…
    }
}

    Note

    If any of the provided promises reject, the returned promise is immediately rejected with that error.

    Warning

    In the event of rejection the other promises will continue to resolve and, as per any other promise, will either fulfill or reject. This is the right pattern for getter style asynchronous tasks, but often for setter tasks (eg. storing data on a server), you most likely will need to wait on all tasks and then act based on which have succeeded and which have failed, in such situations use when(resolved:).

    Note

    when provides NSProgress.

    See also

    when(resolved:)

    Declaration

    Swift

    public func when<U>(fulfilled thenables: [U]) -> Promise<[U.T]> where U : Thenable

    Parameters

    promises

    The promises upon which to wait before the returned promise resolves.

    Return Value

    A new promise that resolves when all the provided promises fulfill or one of the provided promises rejects.

  • Wait for all promises in a set to fulfill.

    Declaration

    Swift

    public func when<U>(fulfilled promises: U...) -> Promise<Void> where U : Thenable, U.T == Void

  • Wait for all promises in a set to fulfill.

    Declaration

    Swift

    public func when<U>(fulfilled promises: [U]) -> Promise<Void> where U : Thenable, U.T == Void

  • Wait for all promises in a set to fulfill.

    Declaration

    Swift

    public func when<U, V>(fulfilled pu: U, _ pv: V) -> Promise<(U.T, V.T)> where U : Thenable, V : Thenable

  • Wait for all promises in a set to fulfill.

    Declaration

    Swift

    public func when<U, V, W>(fulfilled pu: U, _ pv: V, _ pw: W) -> Promise<(U.T, V.T, W.T)> where U : Thenable, V : Thenable, W : Thenable

  • Wait for all promises in a set to fulfill.

    Declaration

    Swift

    public func when<U, V, W, X>(fulfilled pu: U, _ pv: V, _ pw: W, _ px: X) -> Promise<(U.T, V.T, W.T, X.T)> where U : Thenable, V : Thenable, W : Thenable, X : Thenable

  • Wait for all promises in a set to fulfill.

    Declaration

    Swift

    public func when<U, V, W, X, Y>(fulfilled pu: U, _ pv: V, _ pw: W, _ px: X, _ py: Y) -> Promise<(U.T, V.T, W.T, X.T, Y.T)> where U : Thenable, V : Thenable, W : Thenable, X : Thenable, Y : Thenable

  • Generate promises at a limited rate and wait for all to fulfill.

    For example:

    func downloadFile(url: URL) -> Promise<Data> {
    // …
}

let urls: [URL] = /*…

    Declaration

    Swift

    public func when<It>(fulfilled promiseIterator: It, concurrently: Int) -> Promise<[It.Element.T]> where It : IteratorProtocol, It.Element : Thenable

  • Waits on all provided promises.

    when(fulfilled:) rejects as soon as one of the provided promises rejects. when(resolved:) waits on all provided promises whatever their result, and then provides an array of Result<T> so you can individually inspect the results. As a consequence this function returns a Guarantee, ie. errors are lifted from the individual promises into the results array of the returned Guarantee.

    when(resolved: promise1, promise2, promise3).then { results in
    for result in results where case .success(let value) {
       //…
    }
}.catch { error in
    // invalid! Never rejects
}

    Note

    we do not provide tuple variants for when(resolved:) but will accept a pull-request

    Remark

    Doesn’t take Thenable due to protocol associatedtype paradox

    Declaration

    Swift

    public func when<T>(resolved promises: Promise<T>...) -> Guarantee<[Result<T, Error>]>

    Return Value

    A new promise that resolves once all the provided promises resolve. The array is ordered the same as the input, ie. the result order is not resolution order.

  • See

    when(resolved: Promise<T>...)

    Declaration

    Swift

    public func when<T>(resolved promises: [Promise<T>]) -> Guarantee<[Result<T, Error>]>

  • Generate promises at a limited rate and wait for all to resolve.

    For example:

    func downloadFile(url: URL) -> Promise<Data> {
    // ...
}

let urls: [URL] = /*…

    Declaration

    Swift

    public func when<It: IteratorProtocol>(resolved promiseIterator: It, concurrently: Int)
    -> Guarantee<[Result<It.Element.T, Error>]> where It.Element: Thenable

  • Waits on all provided Guarantees.

    Declaration

    Swift

    public func when(_ guarantees: Guarantee<Void>...) -> Guarantee<Void>

  • Undocumented

    Declaration

    Swift

    public func when(guarantees: [Guarantee<Void>]) -> Guarantee<Void>

  • Wait for all cancellable promises in a set to fulfill.

    For example:

    let p = when(fulfilled: promise1, promise2).then { results in
    //…
}.catch { error in
    switch error {
    case URLError.notConnectedToInternet:
        //…
    case CLError.denied:
        //…
    }
}

//…

p.cancel()

    Note

    If any of the provided promises reject, the returned promise is immediately rejected with that error.

    Warning

    In the event of rejection the other promises will continue to resolve and, as per any other promise, will either fulfill or reject. This is the right pattern for getter style asynchronous tasks, but often for setter tasks (eg. storing data on a server), you most likely will need to wait on all tasks and then act based on which have succeeded and which have failed, in such situations use when(resolved:).

    Note

    when provides NSProgress.

    See also

    when(resolved:)

    Declaration

    Swift

    public func when<V>(fulfilled thenables: V...) -> CancellablePromise<[V.U.T]> where V : CancellableThenable

    Parameters

    promises

    The promises upon which to wait before the returned promise resolves.

    Return Value

    A new promise that resolves when all the provided promises fulfill or one of the provided promises rejects.

  • Undocumented

    Declaration

    Swift

    public func when<V>(fulfilled thenables: [V]) -> CancellablePromise<[V.U.T]> where V : CancellableThenable

  • Wait for all cancellable promises in a set to fulfill.

    Declaration

    Swift

    public func when<V>(fulfilled promises: V...) -> CancellablePromise<Void> where V : CancellableThenable, V.U.T == Void

  • Wait for all cancellable promises in a set to fulfill.

    Declaration

    Swift

    public func when<V>(fulfilled promises: [V]) -> CancellablePromise<Void> where V : CancellableThenable, V.U.T == Void

  • Wait for all cancellable promises in a set to fulfill.

    Note

    by convention the cancellable ‘when’ functions should not have a ‘cancellable’ prefix, however the prefix is necessary due to a compiler bug exemplified by the following:

    This works fine:
  1  func hi(_: String...) { }
  2  func hi(_: String, _: String) { }
  3  hi("hi", "there")

This does not compile:
  1  func hi(_: String...) { }
  2  func hi(_: String, _: String) { }
  3  func hi(_: Int...) { }
  4  func hi(_: Int, _: Int) { }
  5
  6  hi("hi", "there")  // Ambiguous use of 'hi' (lines 1 & 2 are candidates)
  7  hi(1, 2)           // Ambiguous use of 'hi' (lines 3 & 4 are candidates)

    See also

    when(fulfilled:,_:)

    Declaration

    Swift

    public func cancellableWhen<U, V>(fulfilled pu: U, _ pv: V) -> CancellablePromise<(U.U.T, V.U.T)> where U : CancellableThenable, V : CancellableThenable

  • Wait for all cancellable promises in a set to fulfill.

    See also

    when(fulfilled:,_:)

    Declaration

    Swift

    public func cancellableWhen<U, V, W>(fulfilled pu: U, _ pv: V, _ pw: W) -> CancellablePromise<(U.U.T, V.U.T, W.U.T)> where U : CancellableThenable, V : CancellableThenable, W : CancellableThenable

  • Wait for all cancellable promises in a set to fulfill.

    See also

    when(fulfilled:,_:)

    Declaration

    Swift

    public func cancellableWhen<U, V, W, X>(fulfilled pu: U, _ pv: V, _ pw: W, _ px: X) -> CancellablePromise<(U.U.T, V.U.T, W.U.T, X.U.T)> where U : CancellableThenable, V : CancellableThenable, W : CancellableThenable, X : CancellableThenable

  • Wait for all cancellable promises in a set to fulfill.

    See also

    when(fulfilled:,_:)

    Declaration

    Swift

    public func cancellableWhen<U, V, W, X, Y>(fulfilled pu: U, _ pv: V, _ pw: W, _ px: X, _ py: Y) -> CancellablePromise<(U.U.T, V.U.T, W.U.T, X.U.T, Y.U.T)> where U : CancellableThenable, V : CancellableThenable, W : CancellableThenable, X : CancellableThenable, Y : CancellableThenable

  • Generate cancellable promises at a limited rate and wait for all to fulfill. Call cancel on the returned promise to cancel all currently pending promises.

    For example:

    func downloadFile(url: URL) -> CancellablePromise<Data> {
    // …
}

let urls: [URL] = /*…

    Declaration

    Swift

    public func when<It>(fulfilled promiseIterator: It, concurrently: Int) -> CancellablePromise<[It.Element.U.T]> where It : IteratorProtocol, It.Element : CancellableThenable

  • Waits on all provided cancellable promises.

    when(fulfilled:) rejects as soon as one of the provided promises rejects. when(resolved:) waits on all provided promises and never rejects. When cancelled, all promises will attempt to be cancelled and those that are successfully cancelled will have a result of PMKError.cancelled.

    let p = when(resolved: promise1, promise2, promise3, cancel: context).then { results in
    for result in results where case .fulfilled(let value) {
       //…
    }
}.catch { error in
    // invalid! Never rejects
}

//…

p.cancel()

    Note

    Any promises that error are implicitly consumed.

    Remark

    Doesn’t take CancellableThenable due to protocol associatedtype paradox

    Declaration

    Swift

    public func when<T>(resolved promises: CancellablePromise<T>...) -> CancellablePromise<[Result<T, Error>]>

    Return Value

    A new promise that resolves once all the provided promises resolve. The array is ordered the same as the input, ie. the result order is not resolution order.

  • Waits on all provided cancellable promises.

    See also

    when(resolved:)

    Declaration

    Swift

    public func when<T>(resolved promises: [CancellablePromise<T>]) -> CancellablePromise<[Result<T, Error>]>