NSFilePresenter: qué es, protocolo NSFileCoordinator y métodos de seguimiento

¿Qué es NSFilePresenter?

NSFilePresenter es un protocolo de Foundation diseñado para rastrear cambios en archivos y directorios en los sistemas operativos de Apple. El protocolo define un conjunto de métodos que el objeto observador implementa para recibir notificaciones de eventos del sistema de archivos.

El propósito principal del protocolo es proporcionar acceso seguro a archivos en escenarios multiproceso. En iOS y macOS, múltiples procesos y subprocesos pueden acceder simultáneamente al mismo archivo a través de NSFileCoordinator, y NSFilePresenter garantiza que cada participante reciba el estado de datos más reciente.

El protocolo está incluido en Foundation desde iOS 5.0 y macOS 10.7. Se utiliza en aplicaciones que trabajan con documentos, bases de datos y cualquier archivo que pueda modificarse simultáneamente desde distintas fuentes — por ejemplo, durante la sincronización de iCloud o la edición colaborativa.

Dónde se usa NSFilePresenter

Aplicaciones basadas en documentos — el área principal de uso de NSFilePresenter. Las aplicaciones que trabajan con UIDocument o NSDocument se registran automáticamente como presentadores a través de NSFileCoordinator. Esto permite manejar correctamente los conflictos al editar el mismo archivo desde múltiples ventanas o dispositivos.

Sincronización de iCloud — el segundo escenario clave. Cuando un archivo se modifica en un dispositivo, iCloud lo sincroniza en todos los dispositivos conectados. NSFilePresenter notifica a la aplicación de estos cambios, permitiendo actualizar la interfaz oportunamente.

Editores multiproceso — el tercer escenario. En aplicaciones donde las colas en segundo plano cargan y guardan datos simultáneamente con el trabajo del usuario, NSFilePresenter previene condiciones de carrera durante la escritura y lectura de archivos.

¿Cómo funciona NSFilePresenter?

El mecanismo de funcionamiento de NSFilePresenter se basa en el modelo de delegación: el objeto implementa los métodos del protocolo, se registra a través de NSFileCoordinator y recibe llamadas cada vez que el archivo rastreado cambia. El sistema mismo determina cuándo ocurre un cambio y qué métodos invocar.

El proceso comienza cuando el objeto crea una instancia de NSFileCoordinator y llama al método del coordinador, pasando la URL del archivo. El coordinador verifica si hay presentadores registrados para esta URL. Si los hay, bloquea el acceso de lectura o escritura y notifica a los presentadores sobre el cambio inminente a través de los métodos del protocolo.

Después de que la operación se completa, el coordinador libera el bloqueo y llama a las notificaciones finales. Es importante señalar que el presentador no controla el flujo de ejecución — solo reacciona a los eventos. NSFileCoordinator es totalmente responsable de la coordinación.

Ciclo de vida de la notificación

Fase de preparación — antes de ejecutar una operación, el coordinador llama a accommodatePresentedItemDeletion o accommodatePresentedSubitemDeletion. El presentador puede manejar la situación o cancelar la operación devolviendo un error. Esta fase permite que la aplicación finalice correctamente el trabajo con el archivo antes de que sea modificado.

Fase de notificación — después de que la operación se completa, el coordinador llama a presentedItemDidChange o presentedSubitemDidChange. El presentador recibe una señal de que el archivo ha cambiado y puede volver a leer su contenido. Para la reubicación de archivos, se llama a presentedItemDidMoveToURL con la nueva ubicación.

Fase de finalización — el coordinador libera todos los bloqueos y recursos. El presentador puede continuar trabajando con los datos actualizados. Las tres fases se ejecutan de forma sincrónica en un solo subproceso, por lo que los métodos del protocolo deben ejecutarse rápidamente sin operaciones de E/S prolongadas.

Métodos principales del protocolo

El protocolo NSFilePresenter contiene varios métodos obligatorios y opcionales. La única propiedad obligatoria es presentedItemURL, que devuelve la URL del archivo o directorio rastreado. Sin esta propiedad, el objeto no puede registrarse como presentador.

Métodos obligatorios

presentedItemURL — una propiedad de tipo URL? que debe devolver la ruta al archivo rastreado. Si el objeto rastrea múltiples archivos, la propiedad devuelve la URL del elemento principal. Para directorios, devuelve la URL del directorio.

presentedItemDidChange — se llama después de que el contenido del archivo rastreado cambie. En este método, el presentador actualiza su estado interno y recarga los datos. Este método no recibe información sobre qué cambió exactamente — solo el hecho del cambio.

Métodos opcionales

accommodatePresentedItemDeletion — se llama antes de la eliminación del archivo. El presentador puede guardar el estado actual, cerrar descriptores de archivo o cancelar la operación devolviendo un NSError. Si el método devuelve un error, la operación de eliminación no se ejecuta.

presentedItemDidMoveToURL — se llama después de la reubicación o cambio de nombre del archivo. El método recibe la nueva URL, y el presentador debe actualizar la referencia al archivo. Sin implementar este método, el presentador seguirá apuntando a la ruta anterior inexistente.

NSFilePresenter y NSFileCoordinator

NSFileCoordinator y NSFilePresenter son un par inseparable. NSFileCoordinator gestiona el acceso a los archivos y llama a los métodos del presentador. El presentador no trabaja directamente con el sistema de archivos — todas las operaciones pasan a través del coordinador, que garantiza la atomicidad de los cambios.

El coordinador registra al presentador mediante el método addFilePresenter de la clase NSFileCoordinator. Después del registro, el presentador comienza a recibir notificaciones. La eliminación se realiza mediante removeFilePresenter. El sistema mantiene una referencia débil al presentador, por lo que el objeto debe permanecer vivo durante todo el período de seguimiento.

Según Apple WWDC 2022, NSFileCoordinator utiliza un mecanismo de coordinación a nivel de kernel, lo que garantiza una latencia mínima durante los bloqueos. En las últimas versiones de iOS, el coordinador está optimizado para trabajar con Sandbox y extensiones de aplicaciones.

Reglas de coordinación

Intention — cada operación de lectura o escritura debe envolverse en un bloque de coordinación: lectura mediante coordinateReadingItemAtURL, escritura mediante coordinateWritingItemAtURL. El coordinador bloquea automáticamente el archivo para otros participantes durante la ejecución del bloque.

Batch coordination — para operaciones con múltiples archivos se utiliza la coordinación por lotes. El coordinador bloquea atómicamente todos los archivos especificados, ejecuta la operación y libera los bloqueos. Esto es críticamente importante al mover o copiar conjuntos de documentos.

Ejemplo de implementación

Creemos una clase DocumentPresenter que implemente el protocolo NSFilePresenter y rastree los cambios de un archivo de documento. La clase contiene una referencia al archivo, datos internos y una bandera de validez.

import Foundation

class DocumentPresenter: NSObject, NSFilePresenter {
    var presentedItemURL: URL? {
        return self.fileURL
    }

    var presentedItemOperationQueue: OperationQueue {
        return self.queue
    }

    private let fileURL: URL
    private let queue = OperationQueue()

    func presentedItemDidChange() {
        self.reloadData()
    }

    func accommodatePresentedItemDeletion() throws {
        try self.saveCurrentState()
    }

    private func reloadData() {
        let coordinator = NSFileCoordinator(filePresenter: self)
        var error: NSError?
        coordinator.coordinate(readingItemAt: self.fileURL,
                               options: [],
                               error: &error)
        { readURL in
            guard let data = try? Data(contentsOf: readURL)
            else { return }
            self.processData(data)
        }
    }

    private func processData(_: Data) {
        // Procesamiento de datos del documento
    }
}

La clase implementa presentedItemDidChange para recargar datos cuando el archivo cambia y accommodatePresentedItemDeletion para guardar el estado antes de la eliminación. La cola de operaciones garantiza que todas las notificaciones se procesen secuencialmente.

El registro del presentador se realiza mediante NSFileCoordinator.addFilePresenter al abrir un documento. Es importante pasar las opciones de lectura correctas al coordinador — withoutChanges para operaciones sin modificación o immediatelyAvailable para escenarios que requieren acceso inmediato.

Errores comunes

El primer error común es la falta de implementación de presentedItemOperationQueue. Si no se especifica una cola, las notificaciones pueden llegar en un subproceso arbitrario, causando condiciones de carrera. Use siempre una OperationQueue secuencial para procesar las notificaciones.

El segundo error es bloquear en los métodos del presentador. Los métodos del protocolo se llaman sincrónicamente desde el coordinador. Si el presentador realiza una operación larga (escritura en BD, solicitud de red), bloquea al coordinador para todos los demás participantes. Mueva las operaciones pesadas a colas en segundo plano.

El tercer error es ignorar accommodatePresentedItemDeletion. Si el presentador no implementa este método y no devuelve un error, el archivo puede eliminarse sin guardar el estado actual. Siempre guarde los datos en este método si aún no se han escrito en el disco.

El cuarto error es la coordinación cíclica. Cuando el presentador dentro de un método de notificación vuelve a llamar al coordinador para el mismo archivo, se produce un interbloqueo. Verifique la bandera isCoordinatedOperation antes de iniciar la coordinación dentro de un controlador.