|
| 1 | +import Foundation |
| 2 | + |
| 3 | +/// A file-based lock for coordinating access to shared resources. |
| 4 | +/// |
| 5 | +/// `FileLock` provides file locking using `flock(2)` to enable safe |
| 6 | +/// concurrent access to cache files from multiple processes. |
| 7 | +/// |
| 8 | +/// ## Usage |
| 9 | +/// |
| 10 | +/// ```swift |
| 11 | +/// let lock = FileLock(path: blobPath) |
| 12 | +/// try await lock.withLock { |
| 13 | +/// // Exclusive access to the resource |
| 14 | +/// try data.write(to: blobPath) |
| 15 | +/// } |
| 16 | +/// ``` |
| 17 | +/// |
| 18 | +/// The lock is automatically released when the closure completes or throws. |
| 19 | +/// |
| 20 | +/// ## Lock File Location |
| 21 | +/// |
| 22 | +/// The lock file is created alongside the target path with a `.lock` extension. |
| 23 | +/// For example, locking `/cache/blobs/abc123` creates `/cache/blobs/abc123.lock`. |
| 24 | +public struct FileLock: Sendable { |
| 25 | + /// The path to the lock file. |
| 26 | + public let lockPath: URL |
| 27 | + |
| 28 | + /// Maximum number of lock acquisition attempts. |
| 29 | + public let maxRetries: Int |
| 30 | + |
| 31 | + /// Delay between retry attempts in seconds. |
| 32 | + public let retryDelay: TimeInterval |
| 33 | + |
| 34 | + /// Creates a file lock for the specified path. |
| 35 | + /// |
| 36 | + /// - Parameters: |
| 37 | + /// - path: The path to the resource being protected. |
| 38 | + /// - maxRetries: Maximum number of lock acquisition attempts. Defaults to 5. |
| 39 | + /// - retryDelay: Delay between retry attempts in seconds. Defaults to 1.0. |
| 40 | + public init(path: URL, maxRetries: Int = 5, retryDelay: TimeInterval = 1.0) { |
| 41 | + self.lockPath = path.appendingPathExtension("lock") |
| 42 | + self.maxRetries = maxRetries |
| 43 | + self.retryDelay = retryDelay |
| 44 | + } |
| 45 | + |
| 46 | + /// Executes the given closure while holding an exclusive lock. |
| 47 | + /// |
| 48 | + /// This method acquires an exclusive lock on the lock file, executes the closure, |
| 49 | + /// and then releases the lock. If the lock cannot be acquired after the maximum |
| 50 | + /// number of retries, an error is thrown. |
| 51 | + /// |
| 52 | + /// - Parameter body: The closure to execute while holding the lock. |
| 53 | + /// - Returns: The value returned by the closure. |
| 54 | + /// - Throws: `FileLockError.acquisitionFailed` if the lock cannot be acquired, |
| 55 | + /// or any error thrown by the closure. |
| 56 | + public func withLockSync<T>(_ body: () throws -> T) throws -> T { |
| 57 | + let handle = try acquireLock() |
| 58 | + defer { releaseLock(handle) } |
| 59 | + return try body() |
| 60 | + } |
| 61 | + |
| 62 | + /// Executes the given async closure while holding an exclusive lock. |
| 63 | + /// |
| 64 | + /// - Parameter body: The async closure to execute while holding the lock. |
| 65 | + /// - Returns: The value returned by the closure. |
| 66 | + /// - Throws: `FileLockError.acquisitionFailed` if the lock cannot be acquired, |
| 67 | + /// or any error thrown by the closure. |
| 68 | + public func withLock<T>(_ body: () async throws -> T) async throws -> T { |
| 69 | + let handle = try await acquireLockAsync() |
| 70 | + defer { releaseLock(handle) } |
| 71 | + return try await body() |
| 72 | + } |
| 73 | + |
| 74 | + // MARK: - |
| 75 | + |
| 76 | + private func prepareLockFile() throws -> FileHandle { |
| 77 | + try FileManager.default.createDirectory( |
| 78 | + at: lockPath.deletingLastPathComponent(), |
| 79 | + withIntermediateDirectories: true |
| 80 | + ) |
| 81 | + |
| 82 | + if !FileManager.default.fileExists(atPath: lockPath.path) { |
| 83 | + FileManager.default.createFile(atPath: lockPath.path, contents: nil) |
| 84 | + } |
| 85 | + |
| 86 | + guard let handle = FileHandle(forWritingAtPath: lockPath.path) else { |
| 87 | + throw FileLockError.acquisitionFailed(lockPath) |
| 88 | + } |
| 89 | + |
| 90 | + return handle |
| 91 | + } |
| 92 | + |
| 93 | + private func tryLock(_ handle: FileHandle) -> Bool { |
| 94 | + flock(handle.fileDescriptor, LOCK_EX | LOCK_NB) == 0 |
| 95 | + } |
| 96 | + |
| 97 | + private func acquireLock() throws -> FileHandle { |
| 98 | + let handle = try prepareLockFile() |
| 99 | + |
| 100 | + for attempt in 0...maxRetries { |
| 101 | + if tryLock(handle) { return handle } |
| 102 | + if attempt < maxRetries { |
| 103 | + Thread.sleep(forTimeInterval: retryDelay) |
| 104 | + } |
| 105 | + } |
| 106 | + |
| 107 | + try? handle.close() |
| 108 | + throw FileLockError.acquisitionFailed(lockPath) |
| 109 | + } |
| 110 | + |
| 111 | + private func acquireLockAsync() async throws -> FileHandle { |
| 112 | + let handle = try prepareLockFile() |
| 113 | + |
| 114 | + for attempt in 0...maxRetries { |
| 115 | + if tryLock(handle) { return handle } |
| 116 | + if attempt < maxRetries { |
| 117 | + try await Task.sleep(for: .seconds(retryDelay)) |
| 118 | + } |
| 119 | + } |
| 120 | + |
| 121 | + try? handle.close() |
| 122 | + throw FileLockError.acquisitionFailed(lockPath) |
| 123 | + } |
| 124 | + |
| 125 | + private func releaseLock(_ handle: FileHandle) { |
| 126 | + flock(handle.fileDescriptor, LOCK_UN) |
| 127 | + try? handle.close() |
| 128 | + // Clean up the lock file after releasing |
| 129 | + try? FileManager.default.removeItem(at: lockPath) |
| 130 | + } |
| 131 | +} |
| 132 | + |
| 133 | +/// Errors that can occur during file locking operations. |
| 134 | +public enum FileLockError: Error, LocalizedError { |
| 135 | + /// The lock could not be acquired after the maximum number of retries. |
| 136 | + case acquisitionFailed(URL) |
| 137 | + |
| 138 | + public var errorDescription: String? { |
| 139 | + switch self { |
| 140 | + case .acquisitionFailed(let path): |
| 141 | + return "Failed to acquire file lock at: \(path.path)" |
| 142 | + } |
| 143 | + } |
| 144 | +} |
0 commit comments