timestral-coreai / swift /Sources /TimestralKit /EngineConfiguration.swift
jbilcke's picture
Publish Timestral CoreAI models, native Swift SDK and validated Python runtime
506f40d verified
Raw History Blame Contribute Delete
4.26 kB
import Foundation
/// Limits cover the native worker pool; queue limits cover waiting input data.
/// Defaults leave 6 GiB available for macOS and other applications.
public struct EngineConfiguration: Sendable, Codable {
public var maxConcurrentWorkers = 1
public var maxQueuedRequests = 128
public var maxQueuedBytes = 128 * 1_024 * 1_024
public var maxTotalWorkerRSSBytes: UInt64 = 4 * 1_024 * 1_024 * 1_024
public var maxWorkerRSSBytes: UInt64 = 3 * 1_024 * 1_024 * 1_024
public var minimumSystemAvailableBytes: UInt64 = 6 * 1_024 * 1_024 * 1_024
public var keepWarmSeconds: Double = 60
public var maxRequestsPerWorker = 128
public var requestTimeoutSeconds: Double = 120
public var cacheMode: WorkerMode = .adaptive
public var memoryCheckIntervalSeconds: Double = 0.1
/// Input + output + attention admission estimate, checked before allocation.
public var maxRequestWorkingBytes: UInt64 = 2 * 1_024 * 1_024 * 1_024
public init() {}
func validate() throws {
guard maxConcurrentWorkers > 0, maxQueuedRequests > 0, maxQueuedBytes > 0,
maxTotalWorkerRSSBytes > 0, maxWorkerRSSBytes > 0,
maxWorkerRSSBytes <= maxTotalWorkerRSSBytes, maxRequestsPerWorker > 0,
keepWarmSeconds.isFinite, keepWarmSeconds >= 0,
requestTimeoutSeconds.isFinite, requestTimeoutSeconds > 0,
memoryCheckIntervalSeconds.isFinite, memoryCheckIntervalSeconds >= 0.02,
maxRequestWorkingBytes > 0 else {
throw EngineError.invalidConfiguration("Limits must be positive; idle retention may be zero and the memory polling interval must be at least 0.02 seconds.")
}
}
}
public enum EngineError: Error, Sendable, LocalizedError {
case invalidConfiguration(String)
case unknownModel(String)
case queueFull(requests: Int, bytes: Int)
case requestTooLarge(estimatedBytes: UInt64, limit: UInt64)
case insufficientMemory(available: UInt64, required: UInt64)
case memoryLimit(String)
case timedOut
case workerFailed(String)
case shutDown
case offloaded
public var errorDescription: String? {
switch self {
case .invalidConfiguration(let text): return text
case .unknownModel(let name): return "No registered Timestral model named \(name)."
case .queueFull(let count, let bytes): return "Timestral queue is full (\(count) waiting requests, \(bytes) bytes). Use bounded producers or retry after capacity is available."
case .requestTooLarge(let bytes, let limit): return "Estimated request working set \(bytes) bytes exceeds the configured \(limit)-byte limit."
case .insufficientMemory(let free, let reserve): return "Available system memory \(free) bytes is below the required \(reserve)-byte reserve."
case .memoryLimit(let detail): return "Timestral stopped a worker at its memory limit: \(detail)"
case .timedOut: return "Timestral request exceeded its time limit."
case .workerFailed(let detail): return "Timestral native worker failed: \(detail)"
case .shutDown: return "Timestral engine is shut down."
case .offloaded: return "The requested model was explicitly offloaded."
}
}
}
/// Cumulative counters and a current pool snapshot. RSS is sampled, not a hard allocation cap.
public struct EngineStatistics: Sendable, Codable {
public internal(set) var queuedRequests = 0
public internal(set) var queuedBytes = 0
public internal(set) var activeRequests = 0
public internal(set) var warmWorkers = 0
public internal(set) var workersStarted = 0
public internal(set) var workersRecycled = 0
public internal(set) var completedRequests = 0
public internal(set) var failedRequests = 0
public internal(set) var cancelledRequests = 0
public internal(set) var rejectedRequests = 0
public internal(set) var currentWorkerRSSBytes: UInt64 = 0
public internal(set) var peakWorkerRSSBytes: UInt64 = 0
public internal(set) var minimumObservedSystemAvailableBytes: UInt64 = .max
public internal(set) var totalQueueWaitSeconds: Double = 0
public internal(set) var totalExecutionSeconds: Double = 0
public init() {}
}