1.1.0 Release

- Added `withLock` and `withTryLock` methods to `ThreadSafeSemaphore` property decorator.
- Added Unit Tests for the above
- Added examples for the above in the README.MD file.

Author: LK-Simon

.gitignore

@@ -89,3 +89,4 @@ fastlane/test_output
 
 iOSInjectionProject/
 .DS_Store
+README.md

README.md

@@ -22,7 +22,7 @@ let package = Package(
     dependencies: [
         .package(
             url: "https://github.com/Flowduino/ThreadSafeSwift.git",
-            .upToNextMajor(from: "1.0.0")
+            .upToNextMajor(from: "1.1.0")
         ),
     ],
     //...
@@ -49,7 +49,7 @@ You can then do `import ThreadSafeSwift` in any code that requires it.
 
 Here are some quick and easy usage examples for the features provided by `ThreadSafeSwift`:
 
-### ThreadSafeSemaphore - Property Wrapper
+### `@ThreadSafeSemaphore` - Property Wrapper
 You can use the `ThreadSafeSemaphore` Property Wrapper to encapsulate any Value Type behind a Thread-Safe `DispatchSemaphore`.
 This is extremely easy for most types:
 ```swift
@@ -84,6 +84,60 @@ func incrementEveryIntegerByOne() {
     myInts = values // This would marshal the `DispatchSempahore` and replace the entire Array with our modified one, then release the `DispatchSemaphore`
 }
 ```
+
+### `ThreadSafeSemaphore.withLock` - Execute a Closure while retaining the Lock
+Often, it is necessary to perform more than one operation on a Value... and when you need to do this, you'll want to ensure that you retain the `DispatchSemaphore` lock against the value for the duration of these operations.
+To facilitate this, we can use the `withLock` method against any `ThreadSafeSemaphore` decorated variable:
+```swift
+@ThreadSafeSemaphore var myInts: [Int] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] 
+```
+Here we have a `ThreadSafeSemaphore` decorated Array of Integers.
+
+If we want to perform any number of operations against any number of values within this Array, we can now do so in a thread-safe manner using `withLock`:
+```swift
+func incrementEachValueByOne() {
+    _myInts.withLock { value in
+        for (index, val) in value.enumerated() {
+            value[index] = val + 1
+        }
+    }
+}
+```
+Please pay attention to the preceeding underscore `_` before `myInts` when invoking the `withLock` method. This is important, as the underscore instructs Swift to reference the Property Decorator rather than its `wrappedValue`.
+
+**IMPORTANT NOTE:** - You must *not* reference the variable itself (in the above example, `myInts`) within the scope of the Closure. If you do, the Thread will lock at that command and proceed no further. All mutations to the value must be performed against `value` as defined within the scope of the Closure itself (as shown above).
+
+So, as you can see, we can now encapsulate *complex types* with the `@ThreadSafeSemaphore` decorator and operate against all of its members within the safety of the `DispatchSemaphore` lock.
+
+### `ThreadSafeSemaphore.withTryLock` - Execute a Closure while retaining the Lock IF we can acquire it, otherwise execute a failure Closure
+As with `ThreadSafeSemaphore.withLock` (explained above), we may need to perform one or more operations within the context of the `DispatchSemaphore` only *if* it is possible to obtain the `DispatchSemaphore` Lock at that time. Where it is not possible to acquire the `DispatchSemaphore` lock at that moment, we may want to execute another piece of conditional code.
+
+We can do that easily:
+```swift
+@ThreadSafeSemaphore var myInts: [Int] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+```
+Again, we declare our `@ThreadSafeSemaphore` decorated Variable.
+
+Now let's see how we would use `withTryLock` against `myInts`:
+```swift
+func incrementEachValueByOne() {
+    _myInts.withTryLock { value in
+        // If we got the Lock
+        for (index, val) in value.enumerated() {
+            value[index] = val + 1
+        }
+    } _: {
+        // If we couldn't get the Lock
+        print("We wanted to acquire the Lock, but couldn't... so we can do something else instead!")
+    }
+}
+```
+**IMPORTANT NOTE:** - You must *not* reference the variable itself (in the above example, `myInts`) within the scope of the *either* Closure. If you do, the Thread will lock at that command and proceed no further. All mutations to the value must be performed against `value` as defined within the scope of the Closure itself (as shown above).
+
+These *Conditional Closures* are extremely useful where your code needs to progress down a different execution path depending on whether it can or cannot acquire the `DispatchSemaphore` lock at the point of execution.
+
+**TIP:** - I use this very approach to implement "Revolving Door Locks" for Collections. A feature that will be added to this library very soon!
+
 ## License
 
 `ThreadSafeSwift` is available under the MIT license. See the [LICENSE file](./LICENSE) for more info.

Sources/ThreadSafeSwift/ThreadSafeSemaphore.swift

@@ -10,7 +10,7 @@ import Foundation
 /**
   Enforces a `DispatchSemaphore` Lock against the given Value Type to ensure single-threaded access.
  - Author: Simon J. Stuart
- - Version: 1.0
+ - Version: 1.1.0
  */
 @propertyWrapper
 public struct ThreadSafeSemaphore<T> {
@@ -31,6 +31,33 @@ public struct ThreadSafeSemaphore<T> {
         }
     }
 
+    /**
+     Invokes your Closure within the confines of the `DispatchSemaphore` Lock (ensuring Mutually-Exclusive Access to your Value for the duration of execution)
+     - Parameters:
+        - code: The code you want to execute while the Lock is engaged.
+     */
+    mutating public func withLock(_ code: @escaping (_ value: inout T) -> ()) {
+        lock.wait()
+        code(&value)
+        lock.signal()
+    }
+    
+    /**
+     Attempts to engage the `DispatchSemaphore` and, if successful, will invoke the Closure you provide to the `onLock` Closure. Otherwise, invokes the code you provide to the `onCannotLock` Closure.
+     - Parameters:
+        - onLock: The code to execute if the `DispatchSemaphore` can be acquired for mutually-exclusive access.
+        - onCannotLock: The code to execute if the `DispatchSemaphore` is currently locked by another Thread.
+     */
+    mutating public func withTryLock(_ onLock: @escaping (_ value: inout T) -> (), _ onCannotLock: @escaping ()->()) {
+        if lock.wait(timeout: DispatchTime.now()) == .success { // If we are able to acquire the lock...
+            onLock(&value) // Invoke the closure within the lock
+            lock.signal() // Release the Lock
+        }
+        else { // If we can't acquire the lock...
+            onCannotLock() // Invoke the closure given to execute when the Lock is unavailable
+        }
+    }
+    
     public init(wrappedValue: T) {
         lock.wait()
         value = wrappedValue

Tests/ThreadSafeSwiftTests/ThreadSafeSwiftTests.swift

@@ -2,10 +2,41 @@ import XCTest
 @testable import ThreadSafeSwift
 
 final class ThreadSafeSwiftTests: XCTestCase {
-    func testExample() throws {
-        // This is an example of a functional test case.
-        // Use XCTAssert and related functions to verify your tests produce the correct
-        // results.
-//        XCTAssertEqual(ThreadSafeSwift().text, "Hello, World!")
+    func testWithLock() throws {
+        @ThreadSafeSemaphore var myInts: [Int] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+        
+        // Increment every Value by 1
+        _myInts.withLock { value in
+            for (index, val) in value.enumerated() {
+                value[index] = val + 1
+            }
+        }
+        // Assert that each Value has been incremented by 1
+        _myInts.withLock { value in
+            for (index, val) in value.enumerated() {
+                XCTAssertEqual(index + 1, val, "Value \(index) should be \(index + 1) but is \(val)")
+            }
+        }
+    }
+    
+    func testTryWithLock() throws {
+        @ThreadSafeSemaphore var myInts: [Int] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+        
+        _myInts.withTryLock { value in
+            // If we got the Lock
+            for (index, val) in value.enumerated() {
+                value[index] = val + 1
+            }
+        } _: {
+            // If we couldn't get the Lock
+            XCTFail("We SHOULD have been able to acquire the Lock, but couldn't")
+        }
+
+        // Assert that each Value has been incremented by 1
+        _myInts.withLock { value in
+            for (index, val) in value.enumerated() {
+                XCTAssertEqual(index + 1, val, "Value \(index) should be \(index + 1) but is \(val)")
+            }
+        }
     }
 }