- Bump to 1.4.0

- Swift 5.3

- Implemented the `AsyncOperationUniquenessPolicy` to handle deduplicating operations

- Implemented `onTimeoutCallback:` to notify users when an operation times out

Author: Bell App Lab

Backgroundable.podspec

@@ -1,7 +1,7 @@
 Pod::Spec.new do |s|
 
   s.name                = "Backgroundable"
-  s.version             = "1.3.4"
+  s.version             = "1.4.0"
   s.summary             = "A collection of handy classes, extensions and global functions to handle being in the background using Swift."
   s.screenshot          = "https://github.com/BellAppLab/Backgroundable/raw/master/Images/backgroundable.png"
 
@@ -24,7 +24,7 @@ It's powerful because it's simple.
   s.osx.deployment_target = "10.12"
   s.tvos.deployment_target = "10.0"
 
-  s.swift_version       = '5.1'
+  s.swift_version       = '5.3'
 
   s.module_name         = 'Backgroundable'
 

Example/Example.xcodeproj/project.pbxproj

@@ -7,6 +7,12 @@
 	objects = {
 
 /* Begin PBXBuildFile section */
+		650BF6DC24D70B80001C531A /* Backgroundable+Operation.swift in Sources */ = {isa = PBXBuildFile; fileRef = 650BF6DB24D70B80001C531A /* Backgroundable+Operation.swift */; };
+		650BF6DD24D70B80001C531A /* Backgroundable+Operation.swift in Sources */ = {isa = PBXBuildFile; fileRef = 650BF6DB24D70B80001C531A /* Backgroundable+Operation.swift */; };
+		650BF6DE24D70B80001C531A /* Backgroundable+Operation.swift in Sources */ = {isa = PBXBuildFile; fileRef = 650BF6DB24D70B80001C531A /* Backgroundable+Operation.swift */; };
+		650BF6E024D7D8E4001C531A /* UniquenessPolicyTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 650BF6DF24D7D8E4001C531A /* UniquenessPolicyTests.swift */; };
+		650BF6E124D7D8E4001C531A /* UniquenessPolicyTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 650BF6DF24D7D8E4001C531A /* UniquenessPolicyTests.swift */; };
+		650BF6E224D7D8E4001C531A /* UniquenessPolicyTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 650BF6DF24D7D8E4001C531A /* UniquenessPolicyTests.swift */; };
 		6553C35E20D944D800405D40 /* AppDelegate.swift in Sources */ = {isa = PBXBuildFile; fileRef = 6553C35D20D944D800405D40 /* AppDelegate.swift */; };
 		6553C36020D944D900405D40 /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 6553C35F20D944D900405D40 /* Assets.xcassets */; };
 		6553C36320D944D900405D40 /* MainMenu.xib in Resources */ = {isa = PBXBuildFile; fileRef = 6553C36120D944D900405D40 /* MainMenu.xib */; };
@@ -134,6 +140,8 @@
 
 /* Begin PBXFileReference section */
 		650B58BC1DA6B8380037CBD7 /* README.md */ = {isa = PBXFileReference; lastKnownFileType = net.daringfireball.markdown; name = README.md; path = ../README.md; sourceTree = "<group>"; };
+		650BF6DB24D70B80001C531A /* Backgroundable+Operation.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "Backgroundable+Operation.swift"; sourceTree = "<group>"; };
+		650BF6DF24D7D8E4001C531A /* UniquenessPolicyTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = UniquenessPolicyTests.swift; sourceTree = "<group>"; };
 		6553C34D20D922DF00405D40 /* Backgroundable+Functions.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "Backgroundable+Functions.swift"; sourceTree = "<group>"; };
 		6553C35220D9233800405D40 /* Backgroundable+OperationQueue.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = "Backgroundable+OperationQueue.swift"; sourceTree = "<group>"; };
 		6553C35B20D944D800405D40 /* macOS Example.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = "macOS Example.app"; sourceTree = BUILT_PRODUCTS_DIR; };
@@ -379,6 +387,7 @@
 				6582320C20D8015E00FA8CC9 /* GlobalFunctionsTests.swift */,
 				6582320D20D8015E00FA8CC9 /* AsyncOperationTests.swift */,
 				6582320E20D8015E00FA8CC9 /* BackgroundQueueTests.swift */,
+				650BF6DF24D7D8E4001C531A /* UniquenessPolicyTests.swift */,
 				6582320F20D8015E00FA8CC9 /* Tests+Aux.swift */,
 			);
 			path = BackgroundableTests;
@@ -398,6 +407,7 @@
 			children = (
 				6582321820D8017200FA8CC9 /* Backgroundable.swift */,
 				6553C35220D9233800405D40 /* Backgroundable+OperationQueue.swift */,
+				650BF6DB24D70B80001C531A /* Backgroundable+Operation.swift */,
 				6553C34D20D922DF00405D40 /* Backgroundable+Functions.swift */,
 			);
 			path = Backgroundable;
@@ -786,6 +796,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				650BF6E224D7D8E4001C531A /* UniquenessPolicyTests.swift in Sources */,
 				6553C39520D9481A00405D40 /* AsyncOperationTests.swift in Sources */,
 				6553C39620D9481A00405D40 /* BackgroundQueueTests.swift in Sources */,
 				6553C39720D9481A00405D40 /* Tests+Aux.swift in Sources */,
@@ -798,6 +809,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				6553C39120D9473800405D40 /* Backgroundable.swift in Sources */,
+				650BF6DE24D70B80001C531A /* Backgroundable+Operation.swift in Sources */,
 				6553C39220D9473800405D40 /* Backgroundable+OperationQueue.swift in Sources */,
 				6553C39320D9473800405D40 /* Backgroundable+Functions.swift in Sources */,
 			);
@@ -808,6 +820,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				6553C3AA20D948B900405D40 /* Backgroundable.swift in Sources */,
+				650BF6DD24D70B80001C531A /* Backgroundable+Operation.swift in Sources */,
 				6553C3AB20D948B900405D40 /* Backgroundable+OperationQueue.swift in Sources */,
 				6553C3AC20D948B900405D40 /* Backgroundable+Functions.swift in Sources */,
 			);
@@ -818,6 +831,7 @@
 			buildActionMask = 2147483647;
 			files = (
 				6553C3BE20D94A2B00405D40 /* Backgroundable.swift in Sources */,
+				650BF6DC24D70B80001C531A /* Backgroundable+Operation.swift in Sources */,
 				6553C3BF20D94A2B00405D40 /* Backgroundable+OperationQueue.swift in Sources */,
 				6553C3C020D94A2B00405D40 /* Backgroundable+Functions.swift in Sources */,
 			);
@@ -845,6 +859,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				650BF6E024D7D8E4001C531A /* UniquenessPolicyTests.swift in Sources */,
 				6582325720D812CF00FA8CC9 /* AsyncOperationTests.swift in Sources */,
 				6582325820D812CF00FA8CC9 /* BackgroundQueueTests.swift in Sources */,
 				6582325920D812CF00FA8CC9 /* Tests+Aux.swift in Sources */,
@@ -856,6 +871,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				650BF6E124D7D8E4001C531A /* UniquenessPolicyTests.swift in Sources */,
 				6582326920D8136E00FA8CC9 /* AsyncOperationTests.swift in Sources */,
 				6582326A20D8136E00FA8CC9 /* BackgroundQueueTests.swift in Sources */,
 				6582326B20D8136E00FA8CC9 /* Tests+Aux.swift in Sources */,
@@ -971,6 +987,7 @@
 				DEBUG_INFORMATION_FORMAT = dwarf;
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
 				ENABLE_TESTABILITY = YES;
+				FRAMEWORK_SEARCH_PATHS = "$(SRCROOT)/../Carthage/build/$(PLATFORM)";
 				GCC_C_LANGUAGE_STANDARD = gnu99;
 				GCC_DYNAMIC_NO_PIC = NO;
 				GCC_NO_COMMON_BLOCKS = YES;
@@ -993,9 +1010,9 @@
 				SDKROOT = iphoneos;
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG;
 				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
-				SWIFT_VERSION = 5.1;
+				SWIFT_VERSION = 5.3;
 				TVOS_DEPLOYMENT_TARGET = 10.0;
-				VERSION = 1.3.4;
+				VERSION = 1.4.0;
 			};
 			name = Debug;
 		};
@@ -1036,6 +1053,7 @@
 				DEBUG_INFORMATION_FORMAT = "dwarf-with-dsym";
 				ENABLE_NS_ASSERTIONS = NO;
 				ENABLE_STRICT_OBJC_MSGSEND = YES;
+				FRAMEWORK_SEARCH_PATHS = "$(SRCROOT)/../Carthage/build/$(PLATFORM)";
 				GCC_C_LANGUAGE_STANDARD = gnu99;
 				GCC_NO_COMMON_BLOCKS = YES;
 				GCC_WARN_64_TO_32_BIT_CONVERSION = YES;
@@ -1050,10 +1068,10 @@
 				PRODUCT_NAME = Backgroundable;
 				SDKROOT = iphoneos;
 				SWIFT_OPTIMIZATION_LEVEL = "-Owholemodule";
-				SWIFT_VERSION = 5.1;
+				SWIFT_VERSION = 5.3;
 				TVOS_DEPLOYMENT_TARGET = 10.0;
 				VALIDATE_PRODUCT = YES;
-				VERSION = 1.3.4;
+				VERSION = 1.4.0;
 			};
 			name = Release;
 		};

README.md

@@ -1,7 +1,7 @@
-# Backgroundable [![Version](https://img.shields.io/badge/Version-1.3.4-black.svg?style=flat)](#installation) [![License](https://img.shields.io/cocoapods/l/Backgroundable.svg?style=flat)](#license)
+# Backgroundable [![Version](https://img.shields.io/badge/Version-1.4.0-black.svg?style=flat)](#installation) [![License](https://img.shields.io/cocoapods/l/Backgroundable.svg?style=flat)](#license)
 
 [![Platforms](https://img.shields.io/badge/Platforms-iOS|tvOS|macOS|Linux-brightgreen.svg?style=flat)](#installation)
-[![Swift support](https://img.shields.io/badge/Swift-3.3%20%7C%204.1%20%7C%204.2-red.svg?style=flat)](#swift-versions-support)
+[![Swift support](https://img.shields.io/badge/Swift-4.2%20%7C%205.3-red.svg?style=flat)](#swift-versions-support)
 [![CocoaPods Compatible](https://img.shields.io/cocoapods/v/Backgroundable.svg?style=flat&label=CocoaPods)](https://cocoapods.org/pods/Backgroundable)
 [![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)
 [![Swift Package Manager compatible](https://img.shields.io/badge/SPM-compatible-orange.svg?style=flat)](https://github.com/apple/swift-package-manager)
@@ -154,6 +154,8 @@ AsyncOperation(timeout: 20, { (op) in
 })
 ```
 
+Optionally, you can set the `onTimeoutCallback:` when instantiating a new `AsyncOperation` to be notified when your operations times out.
+
 ### Cancelations
 
 As per [Apple's documentation](https://developer.apple.com/documentation/foundation/operation/1408418-iscancelled), it's always a good idea to check if your operation has been cancelled during the execution of its closure and shortcircuit it prematurely if needed. For example:
@@ -168,20 +170,38 @@ AsyncOperation({ (op) in
 })
 ```
 
+### Uniqueness Policy
+
+The uniqueness policy dictates whether `AsyncOperation`s with the same `name` should co-exist in a `BackgroundQueue`. This is great for deduplicating operations, for example:
+
+```swift
+@IBAction func refresh(_ sender: UIRefreshControl) {
+    let op = AsyncOperation(name: "Call to API endpoint /xyz", uniquenessPolicy: .drop) { op in
+        //make the call to the API
+        op.finish()
+    }
+    OperationQueue.background.addOperation(op)
+}
+```
+
+This first time the user activates the refresh control, the operation will be added to the queue as normal, because there are no other operations with the name `"Call to API endpoint /xyz"` there yet. But if the user activates the control again before the first call to the API returns, then the `.drop` policy will make sure that a second operation is not added to the queue, since there's one operation with that name in there already. If `.replace` is set, then the previous operation is cancelled and the new one replaces it. 
+
+Neat! 
+
 ## Installation
 
 ### Cocoapods
 
 ```ruby
-pod 'Backgroundable', '~> 1.3'
+pod 'Backgroundable', '~> 1.4'
 ```
 
 Then `import Backgroundable` where needed.
 
 ### Carthage
 
 ```swift
-github "BellAppLab/Backgroundable" ~> 1.3
+github "BellAppLab/Backgroundable" ~> 1.4
 ```
 
 Then `import Backgroundable` where needed.
@@ -190,7 +210,7 @@ Then `import Backgroundable` where needed.
 
 ```swift
 dependencies: [
-    .package(url: "https://github.com/BellAppLab/Backgroundable", from: "1.3")
+    .package(url: "https://github.com/BellAppLab/Backgroundable", from: "1.4")
 ]
 ```
 

Sources/Backgroundable/Backgroundable+Operation.swift

@@ -0,0 +1,68 @@
+//
+//  Backgroundable+Operation.swift
+//  Example
+//
+//  Created by André Campana on 02/08/2020.
+//  Copyright © 2020 Bell App Lab. All rights reserved.
+//
+
+import Foundation
+
+
+@nonobjc
+extension Operation {
+    /**
+     Compares two `Operation`s and returns the one which should be cancelled.
+
+     - parameters:
+        - operation: The second operation to be compared to the receiver.
+
+     - returns:
+        - The operation that should be cancelled between the received and the other operation, according to the receiver's `uniquenessPolicy` flag. If the receiver is not an instance of `AsyncOperation`, `nil` is returned.
+
+     ## See Also:
+     - `AsyncOperationUniquenessPolicy`
+     */
+    func operationToCancel(_ operation: Operation) -> Operation?
+    {
+        guard let policy = (self as? AsyncOperation)?.uniquenessPolicy else { return nil }
+        guard let name = name, let otherName = operation.name, name == otherName else { return nil }
+        guard isFinished == false, operation.isFinished == false else { return nil }
+        guard isCancelled == false, operation.isCancelled == false else { return nil }
+        guard isExecuting == false else { return nil }
+
+        switch policy {
+        case .drop, .ignore: return nil
+        case .replace: return operation
+        }
+    }
+
+    /**
+    Compares two `Operation`s and returns the one which should be added to a queue.
+
+    - parameters:
+       - operation: The second operation to be compared to the receiver.
+
+    - returns:
+       - The operation that should be added between the received and the other operation, according to the receiver's `uniquenessPolicy` flag. If the receiver is not an instance of `AsyncOperation`, `self` is returned.
+
+    ## See Also:
+    - `AsyncOperationUniquenessPolicy`
+    */
+    func operationToAdd(_ operation: Operation) -> Operation?
+    {
+        guard let policy = (self as? AsyncOperation)?.uniquenessPolicy else { return self }
+        guard let name = name, let otherName = operation.name, name == otherName else { return self }
+        guard isFinished == false else { return nil }
+        guard operation.isFinished == false else { return self }
+        guard isCancelled == false else { return nil }
+        guard operation.isCancelled == false else { return self }
+        guard isExecuting == false else { return nil }
+
+
+        switch policy {
+        case .drop, .ignore: return nil
+        case .replace: return self
+        }
+    }
+}

Sources/Backgroundable/Backgroundable+OperationQueue.swift

@@ -76,11 +76,17 @@ public extension OperationQueue
          - timeout: The time in seconds after which this operation should be marked as finished and removed from the queue. Defaults to 10.
          - closure: The closure to be executed by the operation. The closure takes a `AsyncOperation` parameter. Call `finish()` on the object passed here.
      */
-    @nonobjc
+    @objc(addAsyncOperationWithName:timeout:onTimeoutBlock:uniquenessPolicy:andBlock:)
     func addAsyncOperation(name: String? = nil,
                            timeout: TimeInterval = 10,
-                           _ closure: @escaping (_ operation: AsyncOperation) -> Swift.Void)
+                           onTimeoutCallback: AsyncOperationClosure? = nil,
+                           uniquenessPolicy: AsyncOperationUniquenessPolicy = .default,
+                           _ closure: @escaping AsyncOperationClosure)
     {
-        addOperation(AsyncOperation(name: name, timeout: timeout, closure))
+        addOperation(AsyncOperation(name: name,
+                                    timeout: timeout,
+                                    onTimeoutCallback: onTimeoutCallback,
+                                    uniquenessPolicy: uniquenessPolicy,
+                                    closure))
     }
 }