Конфігурація середовища виконання
libvips має область дії процесу. Hokusai ініціалізує її щонайбільше раз, ліниво, і вона лишається доступною до завершення процесу; повторні й паралельні виклики безпечні. Ця сторінка про те, що можна налаштувати, про що можна спитати й як виглядає перевантаження.
Можливості
Section titled “Можливості”Hokusai.capabilities() повідомляє підключені libvips і Cairo та що вміє ця збірка. Доступність кодеків залежить від того, як зібрано libvips, а не від залежностей Hokusai.
let capabilities = try Hokusai.capabilities()print("libvips", capabilities.libvipsVersion, "· Cairo", capabilities.cairoVersion)print("can read :", capabilities.inputFormats.map(\.rawValue).sorted().joined(separator: ", "))print("can write:", capabilities.outputFormats.map(\.rawValue).sorted().joined(separator: ", "))print("text rendering:", capabilities.textRendering, "· HEIF codecs:", capabilities.heifCompressions.map { "\($0)" }.sorted().joined(separator: ", "), "· PNG palette:", capabilities.pngPalette)| Властивість | Значення |
|---|---|
libvipsVersion, cairoVersion |
Підключені версії (8.18.7 і 1.18.6 на машині документації). |
inputFormats, outputFormats |
Набори ImageFormat, які ця збірка може декодувати й кодувати. Читання й запис повідомляються окремо: кодування AVIF перевіряється кодуванням крихітного зображення, бо збереження HEIF може існувати без кодувальника AV1. |
blockedInputFormats |
Формати, що декодуються, але вимкнені через blockUntrustedOperations. Заблоковано — це рішення розгортання; відсутній — потрібна інша libvips. |
textRendering |
Чи можуть drawText / Hokusai.text відтворювати текст (libvips із Pango). |
heifCompressions |
.av1 (AVIF) і .hevc (.heic, часто відсутній). |
pngPalette |
Чи працює індексований PNG (потребує libimagequant або quantizr). |
canDecode(_:) і canEncode(_:) відповідають для одного формату. Ті самі факти друкує hokusai info.
Налаштування
Section titled “Налаштування”Hokusai.configure(_:) фіксує налаштування рівня процесу й може бути викликана один раз, до першого використання середовища. Середовище запускається на initialize(), capabilities() або першій завершальній операції; побудова конвеєра його не запускає.
RuntimeConfiguration |
За замовчуванням | Значення |
|---|---|---|
maxConcurrentEvaluations |
.automatic (активні процесори) |
Скільки завершальних операцій (data(), write(to:)) виконується одночасно. Керує пам’яттю й затримкою; не залежить від vipsConcurrency. |
maxQueuedEvaluations |
nil (без обмеження) |
Скільки може чекати слота, перш ніж нові відхиляються з resource (queuedEvaluations). Обчислення в черзі тримають свої байти джерела, тож обмежуйте за перевантаження. |
vipsConcurrency |
.automatic |
Робочі потоки libvips на одне обчислення зображення. |
blockUntrustedOperations |
false |
Відмовляти завантажувачам, що розбирають складні чи вразливі до зловмисника формати: PDF (poppler), SVG, ImageMagick, OpenSlide. Джерело в заблокованому форматі завершується як decode. PDF-вивід не зачіпається. Завантажувачі JPEG, PNG, WebP, GIF, TIFF і HEIF не блокуються. |
maxOutputPixels |
1 073 741 824 (2³⁰) | Найбільше пікселів, яке може мати будь-яке зображення, створене конвеєром, кінцеве чи проміжне. nil знімає обмеження. Сервіс має задати власну політику. |
// Configuration is chosen once, before the runtime is first used.try Hokusai.configure(.init( maxConcurrentEvaluations: .fixed(1), maxQueuedEvaluations: 1, maxOutputPixels: 50_000_000))let status = Hokusai.runtimeStatusprint("frozen yet?", status.isConfigurationFrozen, "· limit", status.maxConcurrentEvaluations)
// A second call after the runtime has started is refused._ = try Hokusai.capabilities()do { try Hokusai.configure(.init()) } catch { print("configure after use →", error) }
// One slot and one waiting place: of five simultaneous requests, some are rejected up front.let source = try Hokusai(url: URL(fileURLWithPath: "scene.png"))var finished = 0, rejected = 0await withTaskGroup(of: Bool.self) { group in for _ in 0..<5 { group.addTask { do { _ = try await source.blur(sigma: 8).webp().data(); return true } catch { return false } } } for await ok in group { if ok { finished += 1 } else { rejected += 1 } }}print("finished:", finished, "rejected:", rejected)
// maxOutputPixels refuses a pipeline that would create an absurd canvas, before computing anything.do { _ = try await source.resize(width: 100_000).png().data() } catch { print("huge resize →", error) }Що приклад показав на цій машині:
- До використання
runtimeStatusповідомивisConfigurationFrozen: falseі ліміт 1. - Повторний виклик
configureпісля запуску середовища викинувruntime: «runtime configuration is frozen; call configure(_:) before the first Hokusai evaluation, initialize(), or capabilities()». - З одним слотом і чергою на одне місце п’ять одночасних запитів «розмити й закодувати» дали 2 завершені й 3 відхилені (
resource,queuedEvaluations) у цьому запуску. Скільки саме завершиться, залежить від часу; гарантовано, що зайві запити завершуються помилкою одразу, а не накопичуються. resize(width: 100_000)зображення 1600 × 1000 заmaxOutputPixels: 50_000_000викинувresource(outputPixels) «resize would produce a 100000 × 62500 image, above the limit», до обчислення будь-якого пікселя.
Спостереження
Section titled “Спостереження”Hokusai.runtimeStatus — це знімок: чинна конфігурація, isConfigurationFrozen, queuedEvaluations, activeEvaluations, maxConcurrentEvaluations і vipsConcurrency (nil, доки libvips не ініціалізовано). Він описує планувальник Hokusai, а не внутрішні робочі потоки libvips чи пам’ять кодеків.
Життєвий цикл
Section titled “Життєвий цикл”Публічного завершення роботи немає: не додавайте хук завершення до сервера. Hokusai.initialize() необов’язковий, корисний під час запуску, щоб проблему з нативною залежністю перетворити на збій запуску, а не збій першого запиту.