Functions

The following functions are available globally.

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

    Declaration

    Swift

    public func afterCC(seconds: TimeInterval) -> CancellablePromise<Void>

    Return Value

    A cancellable promise that resolves after the specified duration.

    Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

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

    Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func afterCC(_ interval: DispatchTimeInterval) -> CancellablePromise<Void>

    Return Value

    A cancellable promise that resolves after the specified duration.

    Show on GitHub

  • firstly for cancellable promises.

    Compare:

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

// ...

context.cancel()

    With:

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

// ...

context.cancel()

    Note

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

    Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    See

    firstly(execute: () -> Thenable)

    Declaration

    Swift

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

  • Varient of firstly that converts Thenable to CancellablePromise.

    Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func firstlyCC<U>(execute body: () throws -> U) -> CancellablePromise<U.T> where U : Thenable
    Show on GitHub

  • Varient of firstly that converts Guarantee to CancellablePromise.

    Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func firstlyCC<T>(execute body: () -> Guarantee<T>) -> CancellablePromise<T>
    Show on GitHub

  • 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
    Show on GitHub

  • Resolves with the first resolving cancellable promise from a set of cancellable promises. Calling cancel on the race promise cancels all pending promises.

    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.

    Show on GitHub

  • Resolves with the first resolving promise from a set of promises. Calling cancel on the race promise cancels all pending promises.

    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.

    Show on GitHub

  • Resolves with the first resolving Guarantee from a set of cancellable guarantees. Calling cancel on the race promise cancels all pending guarantees.

    let racePromise = race(guarantee1, guarantee2, guarantee3).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<T>(_ guarantees: CancellableGuarantee<T>..., cancelValue: T? = nil) -> CancellableGuarantee<T>

    Return Value

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

    Show on GitHub

  • Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func raceCC<U>(_ thenables: U...) -> CancellablePromise<U.T> where U : Thenable
    Show on GitHub

  • Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func raceCC<U>(_ thenables: [U]) -> CancellablePromise<U.T> where U : Thenable
    Show on GitHub

  • Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func raceCC<T>(_ guarantees: Guarantee<T>..., cancelValue: T? = nil) -> CancellableGuarantee<T>
    Show on GitHub

  • Wait for all 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.

    Show on GitHub

  • Wait for all promises in a set to fulfill, unless cancelled before completion.

    Declaration

    Swift

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

  • Wait for all promises in a set to fulfill, unless cancelled before completion.

    Declaration

    Swift

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

  • Wait for all promises in a set to fulfill, unless cancelled before completion.

    Note

    by convention this function should not have a ‘CC’ suffix, however the suffix 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)

    Declaration

    Swift

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

  • Wait for all promises in a set to fulfill, unless cancelled before completion.

    See also

    whenCC(fulfilled:,_:)

    Declaration

    Swift

    public func whenCC<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
    Show on GitHub

  • Wait for all promises in a set to fulfill, unless cancelled before completion.

    See also

    whenCC(fulfilled:,_:)

    Declaration

    Swift

    public func whenCC<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
    Show on GitHub

  • Wait for all promises in a set to fulfill, unless cancelled before completion.

    See also

    whenCC(fulfilled:,_:)

    Declaration

    Swift

    public func whenCC<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
    Show on GitHub

  • Generate 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
    Show on GitHub

  • Waits on all provided 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()

    Warning

    The returned guarantee cannot be rejected.

    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>...) -> CancellableGuarantee<[PromiseKit.Result<T>]>

    Return Value

    A new guarantee 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.

    Show on GitHub

  • Waits on all provided promises.

    Declaration

    Swift

    public func when<T>(resolved promises: [CancellablePromise<T>]) -> CancellableGuarantee<[Result<T>]>
    Show on GitHub

  • Waits on all provided Guarantees.

    Declaration

    Swift

    public func when(_ guarantees: CancellableGuarantee<Void>...) -> CancellableGuarantee<Void>
    Show on GitHub

  • Waits on all provided Guarantees.

    Declaration

    Swift

    public func when(guarantees: [CancellableGuarantee<Void>]) -> CancellableGuarantee<Void>
    Show on GitHub

  • Wait for all promises in a set to fulfill, unless cancelled before completion.

    Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func whenCC<U>(fulfilled promises: U...) -> CancellablePromise<Void> where U : Thenable, U.T == Void
    Show on GitHub

  • Wait for all promises in a set to fulfill, unless cancelled before completion.

    Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func whenCC<U>(fulfilled promises: [U]) -> CancellablePromise<Void> where U : Thenable, U.T == Void
    Show on GitHub

  • Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func whenCC<U>(fulfilled thenables: [U]) -> CancellablePromise<[U.T]> where U : Thenable
    Show on GitHub

  • Wait for all promises in a set to fulfill, unless cancelled before completion.

    Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func whenCC<U, V>(fulfilled pu: U, _ pv: V) -> CancellablePromise<(U.T, V.T)> where U : Thenable, V : Thenable
    Show on GitHub

  • Wait for all promises in a set to fulfill, unless cancelled before completion.

    Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func whenCC<U, V, W>(fulfilled pu: U, _ pv: V, _ pw: W) -> CancellablePromise<(U.T, V.T, W.T)> where U : Thenable, V : Thenable, W : Thenable
    Show on GitHub

  • Wait for all promises in a set to fulfill, unless cancelled before completion.

    Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func whenCC<U, V, W, X>(fulfilled pu: U, _ pv: V, _ pw: W, _ px: X) -> CancellablePromise<(U.T, V.T, W.T, X.T)> where U : Thenable, V : Thenable, W : Thenable, X : Thenable
    Show on GitHub

  • Wait for all promises in a set to fulfill, unless cancelled before completion.

    Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func whenCC<U, V, W, X, Y>(fulfilled pu: U, _ pv: V, _ pw: W, _ px: X, _ py: Y) -> CancellablePromise<(U.T, V.T, W.T, X.T, Y.T)> where U : Thenable, V : Thenable, W : Thenable, X : Thenable, Y : Thenable
    Show on GitHub

  • Note

    Methods with the CC suffix create a new CancellablePromise, and those without the CC suffix accept an existing CancellablePromise.

    Declaration

    Swift

    public func whenCC<It>(fulfilled promiseIterator: It, concurrently: Int) -> CancellablePromise<[It.Element.T]> where It : IteratorProtocol, It.Element : Thenable
    Show on GitHub

  • Note

    Methods with the CC suffix create a new CancellablePromise or CancellableGuarantee, and those without the CC suffix accept an existing CancellablePromise or CancellableGuarantee.

    Declaration

    Swift

    public func whenCC<T>(resolved promises: Promise<T>...) -> CancellableGuarantee<[PromiseKit.Result<T>]>
    Show on GitHub

  • Note

    Methods with the CC suffix create a new CancellablePromise or CancellableGuarantee, and those without the CC suffix accept an existing CancellablePromise or CancellableGuarantee.

    Declaration

    Swift

    public func whenCC<T>(resolved promises: [Promise<T>]) -> CancellableGuarantee<[PromiseKit.Result<T>]>
    Show on GitHub

  • Note

    Methods with the CC suffix create a new CancellablePromise or CancellableGuarantee, and those without the CC suffix accept an existing CancellablePromise or CancellableGuarantee.

    Declaration

    Swift

    public func whenCC(_ guarantees: Guarantee<Void>...) -> CancellableGuarantee<Void>
    Show on GitHub

  • Note

    Methods with the CC suffix create a new CancellablePromise or CancellableGuarantee, and those without the CC suffix accept an existing CancellablePromise or CancellableGuarantee.

    Declaration

    Swift

    public func whenCC(guarantees: [Guarantee<Void>]) -> CancellableGuarantee<Void>
    Show on GitHub