Перейти до вмісту
Hokusai2.2.2
ivantokar.com

Завершальні операції виводу

Конвеєр нічого не робить, доки не виконається завершальна операція. Вони виконують блокувальну нативну роботу поза кооперативним виконавцем Swift, є async і саме там викидаються помилки декодування, пікселів та кодування. Скасування завдання, що викликає операцію, зупиняє роботу й викидає CancellationError; конвеєр лишається чинним і може бути виконаний знову.

Операція Повертає Для чого
data() Output (data, info) Байти в пам’яті: тіло HTTP, стовпець бази даних. Потребує кодувальника.
write(to:) OutputInfo Файл; записується через тимчасовий файл і перейменовується.
writeChunks(chunkSize:_:) OutputInfo Потокова передача зі зворотним тиском. Потребує кодувальника.
raw(_:premultiplied:background:) RawImage Пікселі без кодування (Необроблені пікселі). Кодувальника не має бути обрано.
metadata() ImageMetadata Заголовок джерела (Перевірка).

OutputInfo містить format, width, height, byteCount і, для PDF, pdf (pageCount, pageWidth, pageHeight).

let image = try Hokusai(url: URL(fileURLWithPath: "scene.png")).resize(width: 400)
// data(): bytes and facts about them. An encoder must be selected.
let output = try await image.webp(quality: 80).data()
print("data():", output.info.format.rawValue, output.info.width, "×", output.info.height, output.info.byteCount, "bytes")
// write(to:) infers the encoder from the extension only when none is selected...
let inferred = try await image.write(to: URL(fileURLWithPath: "inferred.webp"))
print("inferred:", inferred.format.rawValue)
// ...an explicit encoder always wins, whatever the extension says.
let explicit = try await image.png().write(to: URL(fileURLWithPath: "really-png.jpg"))
print("explicit:", explicit.format.rawValue, "written to a .jpg name")
// writeChunks(): bounded, backpressured output for streaming.
var chunks = 0, total = 0
let streamed = try await image.jpeg().writeChunks(chunkSize: 4096) { chunk in
chunks += 1; total += chunk.count
}
print("writeChunks:", chunks, "chunks,", total, "bytes, info says", streamed.byteCount)
// outputFormat is known before evaluation, e.g. to set a Content-Type first.
print("outputFormat:", try image.avif().outputFormat?.rawValue ?? "none", "—", image.outputFormat?.rawValue ?? "none (no encoder)")
// Mistakes are typed errors.
do { _ = try await image.data() } catch { print("no encoder →", error) }
do { _ = try await image.write(to: URL(fileURLWithPath: "out.xyz")) } catch { print("unknown extension →", error) }
  • data() вивів формат, розмір і кількість байтів, які створив.
  • write(to:) визначає кодувальник за розширенням лише тоді, коли ви жодного не обрали (inferred.webp записано як WebP). Явно обраний кодувальник завжди перемагає: png() з іменем .jpg записує дані PNG у really-png.jpg, тож розширення добирайте самі.
  • writeChunks доставив 9 660 байтів трьома шматками не більше ніж по 4 096 байтів, і OutputInfo.byteCount збігся. У передачі тримається щонайбільше chunkSize × 4 байтів закодованого виводу, тож повільний споживач сповільнює кодування замість того, щоб збільшувати пам’ять. chunkSize — 1…67 108 864 (типово 64 КіБ). TIFF не можна записувати лише вперед, тож його спершу кодують у пам’яті, а потім передають шматками. Якщо consume викидає помилку, кодування зупиняється й ця помилка викидається; після збою чи скасування споживач отримав часткову передачу й мусить її відкинути.
  • outputFormat відомий до виконання (avif, а nil, коли кодувальника не обрано), тож сервер може встановити Content-Type до першого байта.

Гарантії файлового виводу

Section titled “Гарантії файлового виводу”

write(to:) пише у тимчасовий файл (.name.hokusai-…) у каталозі призначення й перейменовує його поверх призначення лише по завершенні запису, тож невдалий чи скасований запис залишає наявний файл точно таким, яким він був, і ніколи не лишає пів-зображення. Замінений файл зберігає права доступу; символічне посилання лишається посиланням, а замінюється його ціль. Призначення, що є файлом, який читає конвеєр (зокрема через символічне посилання), відхиляється з invalidOption («output URL») до будь-якого запису: запишіть в інший файл і замініть оригінал самі. Призначення, яке не вдається відкрити чи записати, викидає HokusaiError.io з операцією .write і причиною від системи.

Ситуація Результат
data() чи writeChunks без кодувальника invalidOption(name: "output format", …"call jpeg(), png(), webp(), avif(), pdf(), or encode(using:) before data()")
write(to:) з невідомим розширенням і без кодувальника invalidOption(name: "output URL", …"use a supported image extension or select an encoder")
write(to:) з іменем .svg unsupported: SVG — це формат входу, а не кодувальник
raw з обраним кодувальником invalidOption(name: "raw", …): для закодованого зображення використовуйте data()
Вивід понад RuntimeConfiguration.maxOutputPixels resource (outputPixels), до обчислення будь-якого пікселя

Кодувальник — це конфігурація завершальної операції, а не операція над зображенням: jpeg(quality: 70).resize(width: 300) і resize(width: 300).jpeg(quality: 70) дають байт-у-байт однаковий вивід, а вибір другого кодувальника замінює перший (Порядок операцій).