Repository Public License
1// ORIX Convert — Packages/ORIXConvertCore/Sources/ConvertCore/Jobs/JobModel.swift2// Description: Value types of the conversion queue: requests, job snapshots, states, progress, events, queue3// configuration and the resource-governance rules (concurrency limits from thermal and power state).4// Author: Simon-Pierre Boucher — contact@spboucher.ai5import Foundation6import IOKit.ps78public enum JobState: String, Sendable, Codable, CaseIterable {9 /// Waiting for a slot.10 case queued11 /// Detecting the format, planning, inspecting the source, checking the destination.12 case preparing13 /// An engine is converting.14 case running15 /// The output is being verified, then moved into place.16 case validating17 /// The destination exists and the policy is `askUser`: waiting for `ConversionQueue.resolveConflict`.18 case awaitingDecision19 /// Held back by `pauseJob` before it started.20 case paused21 case finished, failed, cancelled22 /// Nothing was written because the destination existed and the policy is `skip`.23 case skipped2425 /// The job occupies a concurrency slot.26 public var isActive: Bool { self == .preparing || self == .running || self == .validating }27 /// The job will not change again unless it is retried.28 public var isTerminal: Bool { self == .finished || self == .failed || self == .cancelled || self == .skipped }29 /// Terminal, or waiting for a decision only the caller can make.30 public var isSettled: Bool { isTerminal || self == .awaitingDecision }31}3233public enum JobPriority: Int, Sendable, Codable, CaseIterable, Comparable {34 case low = 0, normal = 1, high = 235 public static func < (a: JobPriority, b: JobPriority) -> Bool { a.rawValue < b.rawValue }36}3738/// Where and how the result of a job is written.39public struct OutputDestination: Sendable, Hashable, Codable {40 /// Destination folder; `nil` writes next to the source file.41 public var directory: URL?42 /// Output name template (see `OutputNameTemplate`).43 public var nameTemplate: String44 public var conflictPolicy: ConflictPolicy45 /// With `conflictPolicy == .replace`, allows the output to replace the source file itself.46 public var allowReplacingSource: Bool4748 public init(directory: URL? = nil, nameTemplate: String = OutputNameTemplate.default, conflictPolicy: ConflictPolicy = .rename,49 allowReplacingSource: Bool = false) {50 self.directory = directory; self.nameTemplate = nameTemplate; self.conflictPolicy = conflictPolicy51 self.allowReplacingSource = allowReplacingSource52 }53}5455/// What to convert. One request is one job.56public struct ConversionJobRequest: Sendable {57 /// Input files. One for an ordinary conversion; several only for paths with `acceptsMultipleSources`.58 public var sources: [URL]59 /// Source format; `nil` lets the queue detect it from the content of the first source.60 public var sourceFormat: FormatID?61 public var destinationFormat: FormatID62 public var operation: String?63 /// Options of the conversion. In a chained plan they apply to the last step; the first step uses its defaults.64 public var options: ConversionOptions65 /// Forces one engine's direct path instead of letting the planner choose.66 public var engineID: String?67 public var destination: OutputDestination68 public var priority: JobPriority69 /// Shared by the jobs enqueued together.70 public var batchID: UUID?71 /// 1-based position in the batch, for the `{counter}` name token.72 public var counter: Int73 public var workflowRunID: UUID?74 /// Allows a two-step plan when no direct path exists.75 public var allowChaining: Bool76 /// Writes a row in the history store when the job ends.77 public var recordInHistory: Bool78 /// When the conversion gives several files for a destination that is not a folder (one image per page or per79 /// slide), deliver them in ONE folder named like a single output would have been, instead of scattering them in80 /// the destination. `false` delivers the loose files (workflows set it: their next node handles each file).81 public var groupMultipleOutputs = true8283 public init(sources: [URL], sourceFormat: FormatID? = nil, destinationFormat: FormatID, operation: String? = nil,84 options: ConversionOptions = .init(), engineID: String? = nil, destination: OutputDestination = .init(),85 priority: JobPriority = .normal, batchID: UUID? = nil, counter: Int = 1, workflowRunID: UUID? = nil,86 allowChaining: Bool = true, recordInHistory: Bool = true) {87 self.sources = sources; self.sourceFormat = sourceFormat; self.destinationFormat = destinationFormat88 self.operation = operation; self.options = options; self.engineID = engineID; self.destination = destination89 self.priority = priority; self.batchID = batchID; self.counter = counter; self.workflowRunID = workflowRunID90 self.allowChaining = allowChaining; self.recordInHistory = recordInHistory91 }9293 public init(source: URL, to destinationFormat: FormatID, operation: String? = nil, options: ConversionOptions = .init(),94 destination: OutputDestination = .init(), priority: JobPriority = .normal) {95 self.init(sources: [source], destinationFormat: destinationFormat, operation: operation, options: options,96 destination: destination, priority: priority)97 }98}99100public struct JobLogLine: Sendable, Hashable, Codable {101 public let date: Date102 public let level: LogLevel103 public let message: String104 public init(date: Date = Date(), level: LogLevel, message: String) { self.date = date; self.level = level; self.message = message }105}106107public struct JobProgress: Sendable, Hashable, Codable {108 /// Measured completion of the whole job in 0…1, or `nil` when the engine cannot measure the current step.109 public var fraction: Double?110 public var message: String?111 /// 0-based index of the plan step being executed.112 public var stepIndex: Int113 public var stepCount: Int114 public init(fraction: Double? = nil, message: String? = nil, stepIndex: Int = 0, stepCount: Int = 1) {115 self.fraction = fraction; self.message = message; self.stepIndex = stepIndex; self.stepCount = stepCount116 }117}118119/// The decision a job in `awaitingDecision` is waiting for.120public struct DestinationConflict: Sendable, Hashable, Codable {121 /// The item already present at the destination.122 public let existing: URL123 /// The existing item is one of the job's own source files.124 public let isSource: Bool125 /// `true` when the conversion is already done and only the move is pending; `false` when the conflict was found126 /// before converting (resolving it starts the conversion).127 public let conversionDone: Bool128}129130/// Snapshot of a job. Values are copies: observe `ConversionQueue.events()` for changes.131public struct ConversionJob: Sendable, Identifiable {132 public let id: UUID133 public var request: ConversionJobRequest134 public var state: JobState135 public var priority: JobPriority136 /// Detected (or given) source format, known once the job has been prepared.137 public var sourceFormat: FormatID?138 public var detection: DetectionResult?139 public var plan: ConversionPlan?140 public var progress: JobProgress141 /// Throughput-based estimate, `nil` until a measured fraction has been observed.142 public var estimatedSecondsRemaining: Double?143 public var log: [JobLogLine]144 public var warnings: [ConversionWarning]145 public var checks: [ValidationCheck]146 public var outputs: [CommittedOutput]147 /// Facts the engine measured on its output.148 public var facts: [String: String]149 public var failure: ConversionError?150 public var conflict: DestinationConflict?151 public var createdAt: Date152 public var startedAt: Date?153 public var finishedAt: Date?154 /// 1 for the first run, incremented by `retry`.155 public var attempt: Int156 /// Counts against the heavy-job limit (video, heavy engines, very large files).157 public var isHeavy: Bool158 public var bytesBefore: Int64?159 public var bytesAfter: Int64?160 /// `true` after `cancel` was requested for a running job that has not stopped yet.161 public var cancelRequested: Bool162163 public var error: String? { failure?.errorDescription }164 public var primarySource: URL? { request.sources.first }165 public var duration: TimeInterval? {166 guard let startedAt, let finishedAt else { return nil }167 return finishedAt.timeIntervalSince(startedAt)168 }169}170171public struct QueueStatus: Sendable, Hashable {172 public var isPaused: Bool173 public var limits: ConcurrencyLimits174 public var resources: ResourceState175 public var queued: Int176 public var active: Int177 public var settled: Int178}179180public struct QueueSnapshot: Sendable {181 /// Jobs in display order (the order they will be considered in, within a priority).182 public let jobs: [ConversionJob]183 public let status: QueueStatus184}185186public enum QueueEvent: Sendable {187 case jobAdded(ConversionJob)188 /// State, plan, checks, outputs or priority changed.189 case jobChanged(ConversionJob)190 case jobProgress(id: UUID, progress: JobProgress, estimatedSecondsRemaining: Double?)191 case jobLog(id: UUID, line: JobLogLine)192 case jobWarning(id: UUID, warning: ConversionWarning)193 case jobRemoved(UUID)194 case queueChanged(QueueStatus)195 /// Nothing is running and nothing can start.196 case idle197}198199// MARK: - Resource governance200201public enum ThermalLevel: Int, Sendable, Codable, Comparable {202 case nominal, fair, serious, critical203 public static func < (a: ThermalLevel, b: ThermalLevel) -> Bool { a.rawValue < b.rawValue }204205 public init(_ state: ProcessInfo.ThermalState) {206 switch state {207 case .nominal: self = .nominal208 case .fair: self = .fair209 case .serious: self = .serious210 case .critical: self = .critical211 @unknown default: self = .fair212 }213 }214}215216public struct ResourceState: Sendable, Hashable {217 public var thermal: ThermalLevel218 public var lowPowerMode: Bool219 public var onBattery: Bool220 public init(thermal: ThermalLevel = .nominal, lowPowerMode: Bool = false, onBattery: Bool = false) {221 self.thermal = thermal; self.lowPowerMode = lowPowerMode; self.onBattery = onBattery222 }223}224225/// Source of the machine's thermal and power state. Replaceable in tests.226public protocol ResourceMonitoring: Sendable {227 func currentState() -> ResourceState228}229230/// Reads `ProcessInfo` (thermal state, Low Power Mode) and IOKit power sources (battery or mains).231public struct SystemResourceMonitor: ResourceMonitoring {232 public init() {}233234 public func currentState() -> ResourceState {235 let info = ProcessInfo.processInfo236 return ResourceState(thermal: ThermalLevel(info.thermalState), lowPowerMode: info.isLowPowerModeEnabled, onBattery: Self.isOnBattery())237 }238239 /// `true` when the Mac currently draws from its battery. Desktops without a battery return `false`.240 public static func isOnBattery() -> Bool {241 guard let snapshot = IOPSCopyPowerSourcesInfo()?.takeRetainedValue(),242 let type = IOPSGetProvidingPowerSourceType(snapshot)?.takeUnretainedValue() else { return false }243 return (type as String) == kIOPSBatteryPowerValue244 }245}246247public struct ConcurrencyLimits: Sendable, Hashable {248 /// Jobs allowed to run at once (0 = no new job starts).249 public var total: Int250 /// Heavy jobs allowed to run at once (never more than `total`).251 public var heavy: Int252 /// Why the limits are below the configured ones, when they are.253 public var reason: String?254}255256public struct QueueConfiguration: Sendable, Hashable {257 /// Jobs running at once under normal conditions.258 public var maxConcurrentJobs: Int259 /// Heavy jobs (video, heavy engines, very large files) running at once.260 public var maxHeavyJobs: Int261 /// Engines whose jobs are always heavy (set by the app from the engines it bundles, e.g. the LibreOffice one).262 public var heavyEngineIDs: Set<String>263 /// Source size from which a job is heavy.264 public var heavyFileSize: Int64265 /// Halve the concurrency in Low Power Mode.266 public var reduceInLowPowerMode: Bool267 /// Halve the concurrency when running on battery.268 public var reduceOnBattery: Bool269 /// Lines kept per job log (oldest dropped first).270 public var maxLogLinesPerJob: Int271272 public init(maxConcurrentJobs: Int = QueueConfiguration.defaultConcurrency(), maxHeavyJobs: Int? = nil,273 heavyEngineIDs: Set<String> = [], heavyFileSize: Int64 = 1 << 30, reduceInLowPowerMode: Bool = true,274 reduceOnBattery: Bool = false, maxLogLinesPerJob: Int = 2000) {275 self.maxConcurrentJobs = max(1, maxConcurrentJobs)276 self.maxHeavyJobs = max(1, maxHeavyJobs ?? max(1, self.maxConcurrentJobs / 4))277 self.heavyEngineIDs = heavyEngineIDs; self.heavyFileSize = heavyFileSize278 self.reduceInLowPowerMode = reduceInLowPowerMode; self.reduceOnBattery = reduceOnBattery279 self.maxLogLinesPerJob = max(10, maxLogLinesPerJob)280 }281282 /// Number of performance cores (`hw.perflevel0.physicalcpu`), between 1 and 8; half the active processors when283 /// the sysctl is unavailable.284 public static func defaultConcurrency() -> Int {285 var cores: Int32 = 0286 var size = MemoryLayout<Int32>.size287 if sysctlbyname("hw.perflevel0.physicalcpu", &cores, &size, nil, 0) != 0 || cores <= 0 {288 cores = Int32(max(1, ProcessInfo.processInfo.activeProcessorCount / 2))289 }290 return min(8, max(1, Int(cores)))291 }292293 /// The limits in force for a machine state:294 ///295 /// - thermal `critical`: no new job starts (running jobs are left to finish);296 /// - thermal `serious`: half the configured concurrency (at least 1) and a single heavy job;297 /// - Low Power Mode (when `reduceInLowPowerMode`) or battery (when `reduceOnBattery`): half the configured298 /// concurrency and half the heavy slots (at least 1 each);299 /// - otherwise the configured values. The heavy limit never exceeds the total.300 public func limits(for state: ResourceState) -> ConcurrencyLimits {301 if state.thermal == .critical { return ConcurrencyLimits(total: 0, heavy: 0, reason: "The Mac is too hot: new conversions wait until it cools down.") }302 var total = maxConcurrentJobs, heavy = maxHeavyJobs303 var reasons: [String] = []304 if state.thermal == .serious {305 total = max(1, maxConcurrentJobs / 2); heavy = 1306 reasons.append("thermal pressure")307 }308 if (state.lowPowerMode && reduceInLowPowerMode) || (state.onBattery && reduceOnBattery) {309 total = min(total, max(1, maxConcurrentJobs / 2)); heavy = min(heavy, max(1, maxHeavyJobs / 2))310 reasons.append(state.lowPowerMode && reduceInLowPowerMode ? "Low Power Mode" : "battery power")311 }312 return ConcurrencyLimits(total: total, heavy: min(heavy, total), reason: reasons.isEmpty ? nil : "Reduced concurrency: " + reasons.joined(separator: ", ") + ".")313 }314}315316/// Remaining-time estimate from measured progress only.317public enum ETAEstimator {318 /// Smallest measured fraction from which an estimate is given.319 public static let minimumFraction = 0.01320321 /// `elapsed × (1 − f) / f`, i.e. the remaining work at the throughput observed so far. Returns `nil` when no322 /// fraction has been measured, when it is below `minimumFraction`, or when no time has elapsed.323 public static func remaining(fraction: Double?, elapsed: TimeInterval) -> TimeInterval? {324 guard let fraction, fraction >= minimumFraction, fraction <= 1, elapsed > 0 else { return nil }325 return elapsed * (1 - fraction) / fraction326 }327}328329enum FileSizer {330 /// Size of a file, or the total size of the regular files of a directory (bounded walk).331 static func size(of url: URL) -> Int64? {332 let fm = FileManager.default333 guard let attributes = try? fm.attributesOfItem(atPath: url.path) else { return nil }334 if attributes[.type] as? FileAttributeType != .typeDirectory { return (attributes[.size] as? NSNumber)?.int64Value }335 guard let enumerator = fm.enumerator(at: url, includingPropertiesForKeys: [.fileSizeKey, .isRegularFileKey]) else { return nil }336 var total: Int64 = 0337 var seen = 0338 for case let item as URL in enumerator {339 seen += 1340 if seen > 200_000 { break }341 if let values = try? item.resourceValues(forKeys: [.fileSizeKey, .isRegularFileKey]), values.isRegularFile == true {342 total += Int64(values.fileSize ?? 0)343 }344 }345 return total346 }347}348349final class LockedBox<Value: Sendable>: @unchecked Sendable {350 private let lock = NSLock()351 private var stored: Value352 init(_ value: Value) { stored = value }353 var value: Value { lock.lock(); defer { lock.unlock() }; return stored }354 func mutate(_ body: (inout Value) -> Void) { lock.lock(); body(&stored); lock.unlock() }355}356