CancellableCatchMixin

public protocol CancellableCatchMixin : CancellableThenable

Provides catch and recover to your object that conforms to CancellableThenable

  • catch(on:flags: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: DispatchQueue? = conf.Q.return, flags: DispatchWorkItemFlags? = nil, policy: CatchPolicy = conf.catchPolicy, _ body: @escaping(Error) -> Void) -> CancellableFinalizer

    Parameters

    on

    The queue to which the provided closure dispatches.
    policy

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

    The handler to execute if this promise is rejected.

    Return Value

    A promise finalizer.

    Show on GitHub
  • recover(on:flags:policy:_:) Extension method

    The provided closure executes when this cancellable promise rejects.

    Unlike catch, recover continues the chain. 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? = conf.Q.map, flags: DispatchWorkItemFlags? = nil, policy: CatchPolicy = conf.catchPolicy, _ body: @escaping(Error) throws -> V) -> CancellablePromise<M.T> where V.U.T == M.T

    Parameters

    on

    The queue to which the provided closure dispatches.
    policy

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

    The handler to execute if this promise is rejected.
    Show on GitHub

  • The provided closure executes when this cancellable promise rejects.

    Unlike catch, recover continues the chain. 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

    Note

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

    Declaration

    Swift

    func recoverCC<V: Thenable>(on: DispatchQueue? = conf.Q.map, flags: DispatchWorkItemFlags? = nil, policy: CatchPolicy = conf.catchPolicy, _ body: @escaping(Error) throws -> V) -> CancellablePromise<M.T> where V.T == M.T

    Parameters

    on

    The queue to which the provided closure dispatches.
    policy

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

    The handler to execute if this promise is rejected.
    Show on GitHub

  • The provided closure executes when this promise rejects.

    This variant of recover requires the handler to return a CancellableGuarantee, thus it returns a CancellableGuarantee itself and your closure cannot throw.

    Note

    Note it is logically impossible for this to take a catchPolicy, thus allErrors are handled.

    See also

    Cancellation

    Declaration

    Swift

    @discardableResult
func recover(on: DispatchQueue? = conf.Q.map, flags: DispatchWorkItemFlags? = nil, cancelValue: M.T? = nil, _ body: @escaping(Error) -> CancellableGuarantee<M.T>) -> CancellableGuarantee<M.T>

    Parameters

    on

    The queue to which the provided closure dispatches.
    cancelValue

    optional override value to use when cancelled
    body

    The handler to execute if this promise is rejected.
    Show on GitHub

  • The provided closure executes when this promise rejects.

    This variant of recover requires the handler to return a Guarantee, thus it returns a Guarantee itself and your closure cannot throw.

    Note

    Note it is logically impossible for this to take a catchPolicy, thus allErrors are handled.

    See also

    Cancellation

    Note

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

    Declaration

    Swift

    @discardableResult
func recoverCC(on: DispatchQueue? = conf.Q.map, flags: DispatchWorkItemFlags? = nil, cancelValue: M.T? = nil, _ body: @escaping(Error) -> Guarantee<M.T>) -> CancellableGuarantee<M.T>

    Parameters

    on

    The queue to which the provided closure dispatches.
    cancelValue

    optional override value to use when cancelled
    body

    The handler to execute if this promise is rejected.
    Show on GitHub
  • ensure(on:flags:_:) 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: DispatchQueue? = conf.Q.return, flags: DispatchWorkItemFlags? = nil, _ body: @escaping () -> Void) -> CancellablePromise<M.T>

    Parameters

    on

    The queue to which the provided closure dispatches.
    body

    The closure that executes when this promise resolves.

    Return Value

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

    Show on GitHub
  • ensureThen(on:flags:_:) 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: DispatchQueue? = conf.Q.return, flags: DispatchWorkItemFlags? = nil, _ body: @escaping () -> CancellablePromise<Void>) -> CancellablePromise<M.T>

    Parameters

    on

    The queue to which the provided closure dispatches.
    body

    The closure that executes when this promise resolves.

    Return Value

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

    Show on GitHub
  • 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
    Show on GitHub
  • recover(on:flags:_:) Extension method

    The provided closure executes when this cancellable promise rejects.

    This variant of recover is specialized for Void promises and de-errors your chain returning a CancellableGuarantee, thus you cannot throw and you must handle all errors including cancellation.

    See also

    Cancellation

    Declaration

    Swift

    @discardableResult
func recover(on: DispatchQueue? = conf.Q.map, flags: DispatchWorkItemFlags? = nil, _ body: @escaping(Error) -> Void) -> CancellableGuarantee<Void>

    Parameters

    on

    The queue to which the provided closure dispatches.
    body

    The handler to execute if this promise is rejected.
    Show on GitHub
  • recover(on:flags: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: DispatchQueue? = conf.Q.map, flags: DispatchWorkItemFlags? = nil, policy: CatchPolicy = conf.catchPolicy, _ body: @escaping(Error) throws -> Void) -> CancellablePromise<Void>

    Parameters

    on

    The queue to which the provided closure dispatches.
    policy

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

    The handler to execute if this promise is rejected.
    Show on GitHub