NSFileCoordinator — какво е това, координация на достъпа до iOS файлове

Какво е NSFileCoordinator?

NSFileCoordinator — е механизъм за синхронизация на достъпа до файлове на ниво операционна система, представен от Apple в iOS 5 и macOS 10.7 Lion. За разлика от традиционните заключвания (NSLock, pthread_mutex), координаторът работи на ниво файлова система и може да координира достъпа между различни процеси, а не само между нишките на едно приложение.

Необходимостта от NSFileCoordinator произтича от Sandbox архитектурата в iOS: всеки процес (приложение, разширение, системна услуга) работи в изолирана среда със собствен достъп до файлове. Когато няколко процеса се опитват едновременно да четат и пишат един и същ файл (например при синхронизация на iCloud Drive), без координатор възникват race conditions: процес A чете файла в момента, когато процес B вече частично го е презаписал.

Според WWDC 2023, Apple настоятелно препоръчва използването на NSFileCoordinator за всички файлови операции в Ubiquity container (iCloud Drive) и при работа с File Provider Extension. Игнорирането на координацията е една от честите причини за повреда на данни и невъзпроизводими грешки в iOS приложенията.

Типове координационни намерения (intents)

Координационно намерение (NSFileCoordinator.ReadingIntent / WritingIntent) — е обект, който декларира типа операция, която нишка или процес планира да изпълни. Координаторът използва тези намерения за определяне на реда за достъп и разрешаване на конфликти.

Правила за координация: множество едновременни четения са разрешени (ако няма активно записване), записът е ексклузивен — нито четене, нито запис са разрешени по време на операция за запис. Това съответства на модела readers-writer lock, но с допълнителна поддръжка за междупроцесна координация чрез launchd и XPC.

Важен нюанс: NSFileCoordinator не предотвратява достъпа до файла чрез обикновен NSData или FileManager — координира само онези операции, които са изрично обвити в координационни блокове. Ако друга нишка има достъп до файла директно, заобикаляйки координатора, възникват точно онези race conditions, които координаторът трябва да предотвратява.

NSFileCoordinator в действие: примери с код

Основен модел на използване на NSFileCoordinator се състои от три стъпки: създаване на инстанция на координатора, деклариране на намерение (четене или запис) и изпълнение на операцията вътре в координационния блок. Координаторът гарантира, че никой друг координатор няма да работи едновременно със същия файл.

import Foundation

let coordinator = NSFileCoordinator()
let fileURL = getDocumentURL()

// Безопасно четене
let readIntent = NSFileCoordinator
    .ReadingIntent(url: fileURL)
var content: Data?
var readError: NSError?

coordinator.coordinate(with: readIntent) { error in
    if let error = error {
        readError = error
        return
    }
    content = try? Data(contentsOf: fileURL)
}

// Безопасен запис
let writeIntent = NSFileCoordinator
    .WritingIntent(url: fileURL)

coordinator.coordinate(with: writeIntent) { error in
    guard error == nil else { return }
    do {
        try newData.write(to: fileURL)
    } catch {
        Logger.storage.error(
            "Write failed: \(error)"
        )
    }
}

Пакетна операция — координаторът може да обработва множество файлове в една операция, използвайки масив от намерения. Това е удобно за преместване, копиране или изтриване на набор от файлове като единна транзакция. Ако едно от намеренията не може да бъде изпълнено, цялата операция се отменя с грешка.

let coordinator = NSFileCoordinator()
let readIntent = NSFileCoordinator
    .ReadingIntent(url: sourceURL)
let writeIntent = NSFileCoordinator
    .WritingIntent(url: destURL)

coordinator.coordinate(
    with: [readIntent, writeIntent]
) { error in
    try? FileManager.default
        .copyItem(at: sourceURL, to: destURL)
}

Асинхронна координация — от iOS 15, NSFileCoordinator поддържа асинхронни методи с completion handler, което позволява извършване на координация без блокиране на извикващата нишка. Това е критично важно за UI нишката, където синхронното изчакване на координация може да причини замръзване на интерфейса за секунди.

Протокол NSFilePresenter и уведомления

NSFilePresenter — е протокол, който обект имплементира за получаване на уведомления за промени във файлове, координирани от NSFileCoordinator. Ако вашето приложение показва съдържанието на файл, който може да бъде променен от друг процес (например iCloud Drive синхронизира нова версия), имплементацията на NSFilePresenter позволява своевременно актуализиране на интерфейса.

class DocumentPresenter: NSFilePresenter {
    let presentedItemURL: URL?
    let presentedItemOperationQueue: OperationQueue

    init(url: URL) {
        presentedItemURL = url
        presentedItemOperationQueue = OperationQueue()
    }

    func presentedItemDidChange() {
        DispatchQueue.main.async {
            NotificationCenter.default
                .post(name: .documentDidChange,
                      object: self)
        }
    }

    func presentedItemDidMove(to newURL: URL) {
        Logger.storage.info(
            "File moved to: \(newURL.lastPathComponent)"
        )
    }

    func accommodatePresentedItemDeletion(
        completionHandler: @escaping (Error?) -> Void
    ) {
        Logger.storage.warn("File deleted externally")
        completionHandler(nil)
    }
}

Методи на протокола: presentedItemDidChange се извиква при промяна на съдържанието на файла, presentedItemDidMove(to:) — след преместване на файла, accommodatePresentedItemDeletion — преди изтриване на файла от друг процес (позволява на приложението правилно да затвори файла). Допълнително, протоколът поддържа версиониране чрез presentedItemDidGainVersion: и presentedItemDidLoseVersion:.

Важно: NSFilePresenter трябва да бъде регистриран в системата чрез NSFileCoordinator.addFilePresenter:. Без регистрация уведомленията няма да бъдат доставяни. Регистрацията се извършва еднократно при стартиране на приложението и не изисква повторна регистрация при повторно създаване на презентера.

Най-добри практики за координация на файлове

Винаги използвайте координатора за файлове в Ubiquity container (iCloud Drive) и директории, достъпни за разширения. Дори ако приложението в момента е еднонишково, бъдещи актуализации или системни промени могат да добавят паралелен достъп и липсата на координация ще доведе до трудно откриваеми грешки.

Минимизирайте времето в координационния блок. Докато блокът се изпълнява, други процеси не могат да имат достъп до файла. Продължителните операции вътре в блока (сложна обработка на данни, мрежови заявки) блокират цялата система за достъп до файлове. Изпълнявайте само четене или запис на данни вътре в блока, а обработката — извън него.

Избягвайте deadlock-ове: не извиквайте координатора от вътрешността на блок на друг координатор за същия файл — това ще доведе до взаимно блокиране. Използвайте пакетни операции (масив от намерения) вместо вложени извиквания. Ако влагане е необходимо, използвайте различни опашки или различни URL адреси.

Според objc.io (2024), типичните грешки при работа с NSFileCoordinator включват: липса на обработка на грешки в completion handler (води до незавършени операции); координация само за запис, но не и за четене; използване на остарял синхронен API в UI нишка; игнориране на протокола NSFilePresenter при работа с iCloud Drive. Последната грешка е най-коварна: приложението показва остарели данни, без да знае, че файлът вече е променен.