CancellableCatchMixin

public protocol CancellableCatchMixin : CancellableThenable

Provides catch and recover to your object that conforms to CancellableThenable

  • C

    Type of the delegate catchable

    Declaration

    Swift

    associatedtype C : CatchMixin

  • Delegate catchable for this CancellablePromise

    Declaration

    Swift

    var catchable: C { get }
  • catch(on:policy:_:) Extension method

    The provided closure executes when this cancellable promise rejects.

    Rejecting a promise cascades: rejecting all subsequent promises (unless recover is invoked) thus you will typically place your catch at the end of a chain. Often utility promises will not have a catch, instead delegating the error handling to the caller.

    See also

    Cancellation

    Declaration

    Swift

    @discardableResult
func `catch`(on: Dispatcher = conf.D.return, policy: CatchPolicy = conf.catchPolicy, _ body: @escaping (Error) -> Void) -> CancellableFinalizer

    Parameters

    on

    The dispatcher that executes the provided closure.
    policy

    The default policy does not execute your handler for cancellation errors.
    execute

    The handler to execute if this promise is rejected.

    Return Value

    A promise finalizer.

  • catch(only:on:_:) Extension method

    The provided closure executes when this cancellable promise rejects with the specific error passed in. A final catch is still required at the end of the chain.

    Rejecting a promise cascades: rejecting all subsequent promises (unless recover is invoked) thus you will typically place your catch at the end of a chain. Often utility promises will not have a catch, instead delegating the error handling to the caller.

    Note

    Since this method handles only specific errors, supplying a CatchPolicy is unsupported. You can instead specify e.g. your cancellable error.

    See also

    Cancellation

    Declaration

    Swift

    func `catch`<E>(only: E, on: Dispatcher = conf.D.return, _ body: @escaping (E) -> Void) -> CancellableCascadingFinalizer where E : Equatable, E : Error

    Parameters

    only

    The specific error to be caught and handled.
    on

    The queue to which the provided closure dispatches.
    execute

    The handler to execute if this promise is rejected with the provided error.
  • catch(only:on:policy:_:) Extension method

    The provided closure executes when this cancellable promise rejects with an error of the type passed in. A final catch is still required at the end of the chain.

    Rejecting a promise cascades: rejecting all subsequent promises (unless recover is invoked) thus you will typically place your catch at the end of a chain. Often utility promises will not have a catch, instead delegating the error handling to the caller.

    See also

    Cancellation

    Declaration

    Swift

    func `catch`<E>(only: E.Type, on: Dispatcher = conf.D.return, policy: CatchPolicy = conf.catchPolicy, _ body: @escaping (E) -> Void) -> CancellableCascadingFinalizer where E : Error

    Parameters

    only

    The error type to be caught and handled.
    on

    The queue to which the provided closure dispatches.
    execute

    The handler to execute if this promise is rejected with the provided error type.
  • recover(on:policy:_:) Extension method

    The provided closure executes when this cancellable promise rejects.

    Unlike catch, recover continues the chain. It can return a replacement promise or rethrow. Use recover in circumstances where recovering the chain from certain errors is a possibility. For example:

    let context = firstly {
    CLLocationManager.requestLocation()
}.recover { error in
    guard error == CLError.unknownLocation else { throw error }
    return .value(CLLocation.chicago)
}.cancelContext

//…

context.cancel()

    See also

    Cancellation

    Declaration

    Swift

    func recover<V>(on: Dispatcher = conf.D.map, policy: CatchPolicy = conf.catchPolicy, _ body: @escaping (Error) throws -> V) -> CancellablePromise<C.T> where V : CancellableThenable, Self.C.T == V.U.T

    Parameters

    on

    The dispatcher that executes the provided closure.
    body

    The handler to execute if this promise is rejected.
  • recover(on:policy:_:) Extension method

    The provided closure executes when this cancellable promise rejects.

    Unlike catch, recover continues the chain. It can return a replacement promise or rethrow. Use recover in circumstances where recovering the chain from certain errors is a possibility. For example:

    let context = firstly {
    CLLocationManager.requestLocation()
}.cancellize().recover { error in
    guard error == CLError.unknownLocation else { throw error }
    return Promise.value(CLLocation.chicago)
}.cancelContext

//…

context.cancel()

    See also

    Cancellation

    Declaration

    Swift

    func recover<V>(on: Dispatcher = conf.D.map, policy: CatchPolicy = conf.catchPolicy, _ body: @escaping (Error) throws -> V) -> CancellablePromise<C.T> where V : Thenable, V.T == Self.C.T

    Parameters

    on

    The dispatcher that executes the provided closure.
    policy

    The default policy does not execute your handler for cancellation errors.
    body

    The handler to execute if this promise is rejected.
  • recover(only:on:_:) Extension method

    The provided closure executes when this cancellable promise rejects with the specific error passed in.

    Unlike catch, recover continues the chain. It can return a replacement promise or rethrow. Use recover in circumstances where recovering the chain from certain errors is a possibility. For example:

    firstly {
    CLLocationManager.requestLocation()
}.recover(CLError.unknownLocation) {
    return .value(CLLocation.chicago)
}

    Note

    Since this method recovers only specific errors, supplying a CatchPolicy is unsupported.

    See also

    Cancellation

    Declaration

    Swift

    func recover<V, E>(only: E, on: Dispatcher = conf.D.map, _ body: @escaping (E) throws -> V) -> CancellablePromise<C.T> where V : CancellableThenable, E : Equatable, E : Error, Self.C.T == V.U.T

    Parameters

    only

    The specific error to be recovered (e.g., PMKError.emptySequence)
    on

    The dispatcher that executes the provided closure.
    body

    The handler to execute if this promise is rejected with the provided error.
  • recover(only:on:_:) Extension method

    The provided closure executes when this cancellable promise rejects with the specific error passed in.

    Unlike catch, recover continues the chain. It can return a replacement promise or rethrow. Use recover in circumstances where recovering the chain from certain errors is a possibility. For example:

    firstly {
    CLLocationManager.requestLocation()
}.recover(CLError.unknownLocation) {
    return Promise.value(CLLocation.chicago)
}

    Note

    Since this method recovers only specific errors, supplying a CatchPolicy is unsupported. You can instead specify e.g. your cancellable error.

    See also

    Cancellation

    Declaration

    Swift

    func recover<V, E>(only: E, on: Dispatcher = conf.D.map, _ body: @escaping (E) throws -> V) -> CancellablePromise<C.T> where V : Thenable, E : Equatable, E : Error, V.T == Self.C.T

    Parameters

    only

    The specific error to be recovered.
    on

    The queue to which the provided closure dispatches.
    body

    The handler to execute if this promise is rejected with the provided error.
  • recover(only:on:policy:_:) Extension method

    The provided closure executes when this cancellable promise rejects with an error of the type passed in.

    Unlike catch, recover continues the chain. It can return a replacement promise or rethrow. Use recover in circumstances where recovering the chain from certain errors is a possibility. For example:

    firstly {
    API.fetchData()
}.recover(FetchError.self) { error in
    guard case .missingImage(let partialData) = error else { throw error }
    //…
    return .value(dataWithDefaultImage)
}

    See also

    Cancellation

    Declaration

    Swift

    func recover<V, E>(only: E.Type, on: Dispatcher = conf.D.map, policy: CatchPolicy = conf.catchPolicy, _ body: @escaping (E) throws -> V) -> CancellablePromise<C.T> where V : CancellableThenable, E : Error, Self.C.T == V.U.T

    Parameters

    only

    The error type to be recovered.
    on

    The dispatcher that executes the provided closure.
    policy

    The default policy does not execute your handler for cancellation errors.
    body

    The handler to execute if this promise is rejected with the provided error type.
  • recover(only:on:policy:_:) Extension method

    The provided closure executes when this cancellable promise rejects with an error of the type passed in.

    Unlike catch, recover continues the chain. It can return a replacement promise or rethrow. Use recover in circumstances where recovering the chain from certain errors is a possibility. For example:

    firstly {
    API.fetchData()
}.recover(FetchError.self) { error in
    guard case .missingImage(let partialData) = error else { throw error }
    //…
    return Promise.value(dataWithDefaultImage)
}

    See also

    Cancellation

    Declaration

    Swift

    func recover<V, E>(only: E.Type, on: Dispatcher = conf.D.map, policy: CatchPolicy = conf.catchPolicy, _ body: @escaping (E) throws -> V) -> CancellablePromise<C.T> where V : Thenable, E : Error, V.T == Self.C.T

    Parameters

    only

    The error type to be recovered.
    on

    The queue to which the provided closure dispatches.
    body

    The handler to execute if this promise is rejected with the provided error type.
  • ensure(on:_:) Extension method

    The provided closure executes when this cancellable promise resolves, whether it rejects or not.

    let context = firstly {
    UIApplication.shared.networkActivityIndicatorVisible = true
    //…  returns a cancellable promise
}.done {
    //…
}.ensure {
    UIApplication.shared.networkActivityIndicatorVisible = false
}.catch {
    //…
}.cancelContext

//…

context.cancel()

    Declaration

    Swift

    func ensure(on: Dispatcher = conf.D.return, _ body: @escaping () -> Void) -> CancellablePromise<C.T>

    Parameters

    on

    The dispatcher that executes the provided closure.
    body

    The closure that executes when this promise resolves.

    Return Value

    A new promise, resolved with this promise’s resolution.

  • ensureThen(on:_:) Extension method

    The provided closure executes when this cancellable promise resolves, whether it rejects or not. The chain waits on the returned CancellablePromise<Void>.

    let context = firstly {
    setup() // returns a cancellable promise
}.done {
    //…
}.ensureThen {
    teardown()  // -> CancellablePromise<Void>
}.catch {
    //…
}.cancelContext

//…

context.cancel()

    Declaration

    Swift

    func ensureThen(on: Dispatcher = conf.D.return, _ body: @escaping () -> CancellablePromise<Void>) -> CancellablePromise<C.T>

    Parameters

    on

    The dispatcher that executes the provided closure.
    body

    The closure that executes when this promise resolves.

    Return Value

    A new promise, resolved with this promise’s resolution.

  • cauterize() Extension method

    Consumes the Swift unused-result warning.

    Note

    You should catch, but in situations where you know you don’t need a catch, cauterize makes your intentions clear.

    Declaration

    Swift

    @discardableResult
func cauterize() -> CancellableFinalizer
  • recover(on:flags:policy:_:) Extension method

    The provided closure executes when this cancellable promise rejects.

    Unlike catch, recover continues the chain. It can return a replacement promise or rethrow. Use recover in circumstances where recovering the chain from certain errors is a possibility. For example:

    let context = firstly {
    CLLocationManager.requestLocation()
}.recover { error in
    guard error == CLError.unknownLocation else { throw error }
    return .value(CLLocation.chicago)
}.cancelContext

//…

context.cancel()

    See also

    Cancellation

    Declaration

    Swift

    func recover<V: CancellableThenable>(on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil,
    policy: CatchPolicy = conf.catchPolicy, _ body: @escaping(Error) throws -> V) -> CancellablePromise<C.T> where V.U.T == C.T

    Parameters

    on

    The queue to which the provided closure dispatches.
    flags

    DispatchWorkItemFlags to be applied when dispatching.
    policy

    The default policy does not execute your handler for cancellation errors.
    body

    The handler to execute if this promise is rejected.
  • recover(only:on:flags:_:) Extension method

    The provided closure executes when this cancellable promise rejects with the specific error passed in.

    Unlike catch, recover continues the chain. It can return a replacement promise or rethrow. Use recover in circumstances where recovering the chain from certain errors is a possibility. For example:

    firstly {
    CLLocationManager.requestLocation()
}.recover(CLError.unknownLocation) {
    return .value(CLLocation.chicago)
}

    Note

    Since this method recovers only specific errors, supplying a CatchPolicy is unsupported.

    See also

    Cancellation

    Declaration

    Swift

    func recover<V: CancellableThenable, E: Swift.Error>(only: E, on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil,
    _ body: @escaping(E) throws -> V) -> CancellablePromise<C.T> where V.U.T == C.T, E: Equatable

    Parameters

    only

    The specific error to be recovered (e.g., PMKError.emptySequence)
    on

    The queue to which the provided closure dispatches.
    flags

    DispatchWorkItemFlags to be applied when dispatching.
    body

    The handler to execute if this promise is rejected with the provided error.

  • The provided closure executes when this cancellable promise rejects with an error of the type passed in.

    Unlike catch, recover continues the chain. It can return a replacement promise or rethrow. Use recover in circumstances where recovering the chain from certain errors is a possibility. For example:

    firstly {
    API.fetchData()
}.recover(FetchError.self) { error in
    guard case .missingImage(let partialData) = error else { throw error }
    //…
    return .value(dataWithDefaultImage)
}

    See also

    Cancellation

    Declaration

    Swift

    func recover<V: CancellableThenable, E: Swift.Error>(only: E.Type, on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil,
    policy: CatchPolicy = conf.catchPolicy, _ body: @escaping(E) throws -> V) -> CancellablePromise<C.T> where V.U.T == C.T

    Parameters

    only

    The error type to be recovered.
    on

    The queue to which the provided closure dispatches.
    flags

    DispatchWorkItemFlags to be applied when dispatching.
    policy

    The default policy does not execute your handler for cancellation errors.
    body

    The handler to execute if this promise is rejected with the provided error type.

Available where C.T == Void

  • recover(on:policy:_:) Extension method

    The provided closure executes when this cancellable promise rejects.

    This variant of recover ensures that no error is thrown from the handler and allows specifying a catch policy.

    See also

    Cancellation

    Declaration

    Swift

    func recover(on: Dispatcher = conf.D.map, policy: CatchPolicy = conf.catchPolicy, _ body: @escaping (Error) throws -> Void) -> CancellablePromise<Void>

    Parameters

    on

    The dispatcher that executes the provided closure.
    body

    The handler to execute if this promise is rejected.
  • recover(only:on:_:) Extension method

    The provided closure executes when this cancellable promise rejects with the specific error passed in.

    Unlike catch, recover continues the chain. It can return a replacement promise or rethrow. Use recover in circumstances where recovering the chain from certain errors is a possibility.

    Note

    Since this method recovers only specific errors, supplying a CatchPolicy is unsupported. You can instead specify e.g. your cancellable error.

    See also

    Cancellation

    Declaration

    Swift

    func recover<E: Swift.Error>(only: E, on: Dispatcher = conf.D.map, _ body: @escaping(E) throws -> Void)
    -> CancellablePromise<Void> where E: Equatable

    Parameters

    only

    The specific error to be recovered.
    on

    The queue to which the provided closure dispatches.
    body

    The handler to execute if this promise is rejected with the provided error.
  • recover(only:on:policy:_:) Extension method

    The provided closure executes when this cancellable promise rejects with an error of the type passed in.

    Unlike catch, recover continues the chain. It can return a replacement promise or rethrow. Use recover in circumstances where recovering the chain from certain errors is a possibility.

    See also

    Cancellation

    Declaration

    Swift

    func recover<E>(only: E.Type, on: Dispatcher = conf.D.map, policy: CatchPolicy = conf.catchPolicy, _ body: @escaping (E) throws -> Void) -> CancellablePromise<Void> where E : Error

    Parameters

    only

    The error type to be recovered.
    on

    The queue to which the provided closure dispatches.
    body

    The handler to execute if this promise is rejected with the provided error type.