NSFileCoordinator — что это, координация доступа к файлам iOS

Что такое NSFileCoordinator?

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

Необходимость в NSFileCoordinator возникает из-за архитектуры Sandbox в iOS: каждый процесс (приложение, расширение, системный сервис) работает в изолированном окружении с собственным доступом к файлам. Когда несколько процессов пытаются одновременно читать и писать один файл (например, при синхронизации iCloud Drive), без координатора возникают состояния гонки: процесс 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()

// Safe reading
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)
}

// Safe writing
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. Последняя ошибка — самая коварная: приложение показывает устаревшие данные, не подозревая, что файл уже изменён.