Merge pull request #1045 from GarthSnyder/wrapper-revamp

Wrapper revamp

Sources/CancellablePromise.swift → Sources/Cancellation/CancellablePromise.swift

@@ -72,7 +72,7 @@ public class CancellablePromise<T>: CancellableThenable, CancellableCatchMixin {
             // Wrapper promise
             promise = Promise { seal in
                 reject = seal.reject
-                bridge.done(on: nil) {
+                bridge.done(on: CurrentThreadDispatcher()) {
                     seal.fulfill($0)
                 }.catch(policy: .allErrors) {
                     seal.reject($0)

Sources/Dispatchers/ConcurrencyLimitedDispatcher.swift

@@ -3,7 +3,7 @@ import Foundation
 /// A PromiseKit Dispatcher that allows no more than X simultaneous
 /// executions at once.
 
-public class ConcurrencyLimitedDispatcher: Dispatcher {
+public final class ConcurrencyLimitedDispatcher: Dispatcher {
 
     let queue: Dispatcher
     let serializer: DispatchQueue = DispatchQueue(label: "CLD serializer")

Sources/Dispatchers/RateLimitedDispatcher.swift

@@ -19,7 +19,7 @@ import Foundation
 ///
 /// 100% thread safe.
 
-public class RateLimitedDispatcher: RateLimitedDispatcherBase {
+public final class RateLimitedDispatcher: RateLimitedDispatcherBase {
 
     private var tokensInBucket: Double = 0
     private var latestAccrual: DispatchTime = DispatchTime.now()

Sources/Dispatchers/StrictRateLimitedDispatcher.swift

@@ -19,7 +19,7 @@ import Foundation
 ///
 /// 100% thread safe.
 
-public class StrictRateLimitedDispatcher: RateLimitedDispatcherBase {
+public final class StrictRateLimitedDispatcher: RateLimitedDispatcherBase {
 
     internal var startTimeHistory: Queue<DispatchTime>
     private var immediateDispatchesAvailable: Int

Sources/Wrappers/CatchWrappers.swift

@@ -0,0 +1,73 @@
+import Dispatch
+
+public extension _PMKCatchWrappers {
+
+    /**
+     The provided closure executes when this 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.
+     
+     - Parameter on: The queue to which the provided closure dispatches.
+     - Parameter flags: `DispatchWorkItemFlags` to be applied when dispatching.
+     - Parameter policy: The default policy does not execute your handler for cancellation errors.
+     - Parameter body: The handler to execute if this promise is rejected.
+     - Returns: A promise finalizer.
+     - SeeAlso: [Cancellation](http://https://github.com/mxcl/PromiseKit/blob/master/Documents/CommonPatterns.md#cancellation/docs/)
+     */
+    @discardableResult
+    func `catch`(on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil, policy: CatchPolicy = conf.catchPolicy, _ body: @escaping(Error) -> Void) -> Finalizer {
+        let dispatcher = selectDispatcher(given: on, configured: conf.D.return, flags: flags)
+        return `catch`(on: dispatcher, policy: policy, body)
+    }
+
+    /**
+     The provided closure executes when this 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.
+     
+     - Parameter only: The specific error to be caught and handled (e.g., `PMKError.emptySequence`).
+     - Parameter on: The queue to which the provided closure dispatches.
+     - Parameter flags: `DispatchWorkItemFlags` to be applied when dispatching.
+     - Parameter body: The handler to execute if this promise is rejected with the provided error.
+     - Note: Since this method handles only specific errors, supplying a `CatchPolicy` is unsupported.
+     - SeeAlso: [Cancellation](http://promisekit.org/docs/)
+     */
+    func `catch`<E: Swift.Error>(only: E, on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil, _ body: @escaping(E) -> Void)
+        -> CascadingFinalizer where E: Equatable
+    {
+        let dispatcher = selectDispatcher(given: on, configured: conf.D.return, flags: flags)
+        return `catch`(only: only, on: dispatcher, body)
+    }
+
+    /**
+     The provided closure executes when this 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.
+     
+     - Parameter only: The error type to be caught and handled (e.g., `PMKError`).
+     - Parameter on: The queue to which the provided closure dispatches.
+     - Parameter flags: `DispatchWorkItemFlags` to be applied when dispatching.
+     - Parameter policy: A `CatchPolicy` that further constrains the errors this handler will see. E.g., if
+     you are receiving `PMKError` errors, do you want to see even those that result from cancellation?
+     - Parameter body: The handler to execute if this promise is rejected with the provided error type.
+     - SeeAlso: [Cancellation](http://promisekit.org/docs/)
+     */
+    func `catch`<E: Swift.Error>(only: E.Type, on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil,
+        policy: CatchPolicy = conf.catchPolicy, _ body: @escaping(E) -> Void) -> CascadingFinalizer
+    {
+        let dispatcher = selectDispatcher(given: on, configured: conf.D.return, flags: flags)
+        return `catch`(only: only, on: dispatcher, policy: policy, body)
+    }
+
+}
+
+

Sources/Wrappers/EnsureWrappers.swift

@@ -0,0 +1,51 @@
+import Dispatch
+
+public extension _PMKSharedWrappers {
+
+    /**
+     The provided closure executes when this promise resolves, whether it rejects or not.
+     
+         firstly {
+             UIApplication.shared.networkActivityIndicatorVisible = true
+         }.done {
+             //…
+         }.ensure {
+             UIApplication.shared.networkActivityIndicatorVisible = false
+         }.catch {
+             //…
+         }
+     
+     - Parameter on: The queue to which the provided closure dispatches.
+     - Parameter flags: `DispatchWorkItemFlags` to be applied when dispatching.
+     - Parameter body: The closure that executes when this promise resolves.
+     - Returns: A new promise, resolved with this promise’s resolution.
+     */
+    func ensure(on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil, _ body: @escaping () -> Void) -> BaseOfT {
+        let dispatcher = selectDispatcher(given: on, configured: conf.D.return, flags: flags)
+        return ensure(on: dispatcher, body)
+    }
+
+    /**
+     The provided closure executes when this promise resolves, whether it rejects or not.
+     The chain waits on the returned `Guarantee<Void>`.
+
+         firstly {
+             setup()
+         }.done {
+             //…
+         }.ensureThen {
+             teardown()
+         }.catch {
+             //…
+         }
+
+     - Parameter on: The queue to which the provided closure dispatches.
+     - Parameter flags: `DispatchWorkItemFlags` to be applied when dispatching.
+     - Parameter body: The closure that executes when this promise resolves.
+     - Returns: A new promise, resolved with this promise’s resolution.
+     */
+    func ensureThen(on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil, _ body: @escaping () -> VoidReturn) -> BaseOfT {
+        let dispatcher = selectDispatcher(given: on, configured: conf.D.return, flags: flags)
+        return ensureThen(on: dispatcher, body)
+    }
+}

Sources/Wrappers/FinallyWrappers.swift

@@ -0,0 +1,11 @@
+import Dispatch
+
+public extension _PMKFinallyWrappers {
+    /// `finally` is the same as `ensure`, but it is not chainable
+    @discardableResult
+    func finally(on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil, _ body: @escaping () -> Void) -> FinallyReturn {
+        let dispatcher = selectDispatcher(given: on, configured: conf.D.return, flags: flags)
+        return finally(on: dispatcher, body)
+    }
+}
+

Sources/Wrappers/GuaranteeWrappers.swift

@@ -0,0 +1,39 @@
+// Since Guarantees have no error path, closures in the API are nonthrowing, which
+// makes them different from the shared Promise/CancellablePromise API.
+
+import Dispatch
+
+public extension Guarantee {
+
+    @discardableResult
+    func then<U>(on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil, _ body: @escaping(T) -> Guarantee<U>) -> Guarantee<U> {
+        let dispatcher = selectDispatcher(given: on, configured: conf.D.map, flags: flags)
+        return then(on: dispatcher, body)
+    }
+
+    func map<U>(on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil, _ body: @escaping(T) -> U) -> Guarantee<U> {
+        let dispatcher = selectDispatcher(given: on, configured: conf.D.map, flags: flags)
+        return map(on: dispatcher, body)
+    }
+
+    @discardableResult
+    func done(on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil, _ body: @escaping(T) -> Void) -> Guarantee<Void> {
+        let dispatcher = selectDispatcher(given: on, configured: conf.D.return, flags: flags)
+        return done(on: dispatcher, body)
+    }
+
+    func get(on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil, _ body: @escaping (T) -> Void) -> Guarantee<T> {
+        let dispatcher = selectDispatcher(given: on, configured: conf.D.return, flags: flags)
+        return get(on: dispatcher, body)
+    }
+}
+
+public extension Guarantee where T: Sequence {
+
+    func thenMap<U>(on: DispatchQueue? = .pmkDefault, flags: DispatchWorkItemFlags? = nil, _ transform: @escaping(T.Iterator.Element) -> Guarantee<U>) -> Guarantee<[U]> {
+        let dispatcher = selectDispatcher(given: on, configured: conf.D.map, flags: flags)
+        return thenMap(on: dispatcher, transform)
+    }
+
+}
+