ContainerizationExtras: Add AsyncMutex (#324)

We already have `AsyncLock`, but in some cases it'd be nice to have the
type protect a piece of data that you access through the lock, much like
the Synchronization frameworks new `Mutex` type.

This change adds such a type.

Author: dcantah

Sources/ContainerizationExtras/AsyncMutex.swift

@@ -0,0 +1,59 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025 Apple Inc. and the Containerization project authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//===----------------------------------------------------------------------===//
+
+/// `AsyncMutex` provides a mutex that protects a piece of data, with the main benefit being that it
+/// is safe to call async methods while holding the lock. This is primarily used in spots
+/// where an actor makes sense, but we may need to ensure we don't fall victim to actor
+/// reentrancy issues.
+public actor AsyncMutex<T: Sendable> {
+    private final class Box: @unchecked Sendable {
+        var value: T
+        init(_ value: T) {
+            self.value = value
+        }
+    }
+
+    private var busy = false
+    private var queue: ArraySlice<CheckedContinuation<(), Never>> = []
+    private let box: Box
+
+    public init(_ initialValue: T) {
+        self.box = Box(initialValue)
+    }
+
+    /// withLock provides a scoped locking API to run a function while holding the lock.
+    /// The protected value is passed to the closure for safe access.
+    public func withLock<R: Sendable>(_ body: @Sendable @escaping (inout T) async throws -> R) async rethrows -> R {
+        while self.busy {
+            await withCheckedContinuation { cc in
+                self.queue.append(cc)
+            }
+        }
+
+        self.busy = true
+
+        defer {
+            self.busy = false
+            if let next = self.queue.popFirst() {
+                next.resume(returning: ())
+            } else {
+                self.queue = []
+            }
+        }
+
+        return try await body(&self.box.value)
+    }
+}

Tests/ContainerizationExtrasTests/AsyncMutexTests.swift

@@ -0,0 +1,132 @@
+//===----------------------------------------------------------------------===//
+// Copyright © 2025 Apple Inc. and the Containerization project authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//===----------------------------------------------------------------------===//
+
+import Foundation
+import Testing
+
+@testable import ContainerizationExtras
+
+final class AsyncMutexTests {
+    @Test
+    func testBasicModification() async throws {
+        let mutex = AsyncMutex(0)
+
+        let result = await mutex.withLock { value in
+            value += 1
+            return value
+        }
+
+        #expect(result == 1)
+    }
+
+    @Test
+    func testMultipleModifications() async throws {
+        let mutex = AsyncMutex(0)
+
+        await mutex.withLock { value in
+            value += 5
+        }
+
+        let result = await mutex.withLock { value in
+            value += 10
+            return value
+        }
+
+        #expect(result == 15)
+    }
+
+    @Test
+    func testConcurrentAccess() async throws {
+        let mutex = AsyncMutex(0)
+        let iterations = 100
+
+        await withTaskGroup(of: Void.self) { group in
+            for _ in 0..<iterations {
+                group.addTask {
+                    await mutex.withLock { value in
+                        value += 1
+                    }
+                }
+            }
+        }
+
+        let finalValue = await mutex.withLock { value in
+            value
+        }
+
+        #expect(finalValue == iterations)
+    }
+
+    @Test
+    func testAsyncOperationsUnderLock() async throws {
+        let mutex = AsyncMutex([Int]())
+
+        await mutex.withLock { value in
+            try? await Task.sleep(for: .milliseconds(10))
+            value.append(1)
+        }
+
+        await mutex.withLock { value in
+            try? await Task.sleep(for: .milliseconds(10))
+            value.append(2)
+        }
+
+        let result = await mutex.withLock { value in
+            value
+        }
+
+        #expect(result == [1, 2])
+    }
+
+    @Test
+    func testThrowingClosure() async throws {
+        let mutex = AsyncMutex(0)
+
+        await #expect(throws: POSIXError.self) {
+            try await mutex.withLock { value in
+                value += 1
+                throw POSIXError(.ENOENT)
+            }
+        }
+
+        // Value should still be modified even though closure threw
+        let result = await mutex.withLock { value in
+            value
+        }
+
+        #expect(result == 1)
+    }
+
+    @Test
+    func testComplexDataStructure() async throws {
+        struct Counter: Sendable {
+            var count: Int
+            var label: String
+        }
+
+        let mutex = AsyncMutex(Counter(count: 0, label: "test"))
+
+        await mutex.withLock { value in
+            value.count += 10
+            value.label = "modified"
+        }
+
+        await mutex.withLock { value in
+            #expect(value.count == 10)
+            #expect(value.label == "modified")
+        }
+    }
+}