NSFilePresenter: o que é, protocolo NSFileCoordinator e métodos de rastreamento

O que é NSFilePresenter?

NSFilePresenter é um protocolo Foundation projetado para rastrear alterações em arquivos e diretórios nos sistemas operacionais da Apple. O protocolo define um conjunto de métodos que o objeto observador implementa para receber notificações de eventos do sistema de arquivos.

O principal objetivo do protocolo é fornecer acesso seguro a arquivos em cenários multithread. No iOS e macOS, múltiplos processos e threads podem acessar simultaneamente o mesmo arquivo através do NSFileCoordinator, e o NSFilePresenter garante que cada participante receba o estado mais recente dos dados.

O protocolo está incluído no Foundation desde iOS 5.0 e macOS 10.7. É usado em aplicações que trabalham com documentos, bancos de dados e qualquer arquivo que possa ser modificado simultaneamente de diferentes fontes — por exemplo, durante a sincronização do iCloud ou edição colaborativa.

Onde NSFilePresenter é usado

Aplicações baseadas em documentos — a principal área de uso do NSFilePresenter. Aplicações que trabalham com UIDocument ou NSDocument se registram automaticamente como apresentadores através do NSFileCoordinator. Isso permite lidar corretamente com conflitos ao editar o mesmo arquivo de múltiplas janelas ou dispositivos.

Sincronização iCloud — o segundo cenário chave. Quando um arquivo é modificado em um dispositivo, o iCloud o sincroniza em todos os dispositivos conectados. O NSFilePresenter notifica a aplicação dessas alterações, permitindo atualizar a interface oportunamente.

Editores multithread — o terceiro cenário. Em aplicações onde filas em segundo plano carregam e salvam dados simultaneamente com o trabalho do usuário, o NSFilePresenter previne condições de corrida durante a escrita e leitura de arquivos.

Como funciona o NSFilePresenter?

O mecanismo de funcionamento do NSFilePresenter é baseado no modelo de delegação: o objeto implementa os métodos do protocolo, se registra através do NSFileCoordinator e recebe chamadas sempre que o arquivo rastreado muda. O próprio sistema determina quando uma alteração ocorre e quais métodos invocar.

O processo começa quando o objeto cria uma instância do NSFileCoordinator e chama o método do coordenador, passando a URL do arquivo. O coordenador verifica se há apresentadores registrados para esta URL. Se sim, ele bloqueia o acesso de leitura ou escrita e notifica os apresentadores sobre a mudança iminente através dos métodos do protocolo.

Após a conclusão da operação, o coordenador libera o bloqueio e chama as notificações finais. É importante notar que o apresentador não controla o fluxo de execução — ele apenas reage aos eventos. O NSFileCoordinator é totalmente responsável pela coordenação.

Ciclo de vida da notificação

Fase de preparação — antes de executar uma operação, o coordenador chama accommodatePresentedItemDeletion ou accommodatePresentedSubitemDeletion. O apresentador pode lidar com a situação ou cancelar a operação retornando um erro. Esta fase permite que a aplicação finalize corretamente o trabalho com o arquivo antes de ele ser modificado.

Fase de notificação — após a conclusão da operação, o coordenador chama presentedItemDidChange ou presentedSubitemDidChange. O apresentador recebe um sinal de que o arquivo mudou e pode reler seu conteúdo. Para realocação de arquivos, presentedItemDidMoveToURL é chamado com a nova localização.

Fase de conclusão — o coordenador libera todos os bloqueios e recursos. O apresentador pode continuar trabalhando com os dados atualizados. Todas as três fases são executadas de forma síncrona em uma única thread, portanto os métodos do protocolo devem executar rapidamente sem operações longas de E/S.

Métodos principais do protocolo

O protocolo NSFilePresenter contém vários métodos obrigatórios e opcionais. A única propriedade obrigatória é presentedItemURL, que retorna a URL do arquivo ou diretório rastreado. Sem esta propriedade, o objeto não pode ser registrado como apresentador.

Métodos obrigatórios

presentedItemURL — uma propriedade do tipo URL? que deve retornar o caminho para o arquivo rastreado. Se o objeto rastreia múltiplos arquivos, a propriedade retorna a URL do item principal. Para diretórios, retorna a URL do diretório.

presentedItemDidChange — chamado após o conteúdo do arquivo rastreado mudar. Neste método, o apresentador atualiza seu estado interno e recarrega os dados. Este método não recebe informação sobre o que exatamente mudou — apenas o fato da mudança.

Métodos opcionais

accommodatePresentedItemDeletion — chamado antes da exclusão do arquivo. O apresentador pode salvar o estado atual, fechar descritores de arquivo ou cancelar a operação retornando um NSError. Se o método retornar um erro, a operação de exclusão não é executada.

presentedItemDidMoveToURL — chamado após a realocação ou renomeação do arquivo. O método recebe a nova URL, e o apresentador deve atualizar a referência ao arquivo. Sem implementar este método, o apresentador continuará apontando para o caminho antigo e inexistente.

NSFilePresenter e NSFileCoordinator

NSFileCoordinator e NSFilePresenter são um par inseparável. NSFileCoordinator gerencia o acesso aos arquivos e chama os métodos do apresentador. O apresentador não trabalha diretamente com o sistema de arquivos — todas as operações passam pelo coordenador, que garante a atomicidade das alterações.

O coordenador registra o apresentador através do método addFilePresenter da classe NSFileCoordinator. Após o registro, o apresentador começa a receber notificações. A remoção é feita através do removeFilePresenter. O sistema mantém uma referência fraca ao apresentador, portanto o objeto deve permanecer vivo durante todo o período de rastreamento.

De acordo com a Apple WWDC 2022, NSFileCoordinator usa um mecanismo de coordenação a nível de kernel, garantindo latência mínima durante os bloqueios. Nas versões mais recentes do iOS, o coordenador é otimizado para trabalhar com Sandbox e extensões de aplicativos.

Regras de coordenação

Intention — cada operação de leitura ou escrita deve ser envolvida em um bloco de coordenação: leitura através de coordinateReadingItemAtURL, escrita através de coordinateWritingItemAtURL. O coordenador automaticamente bloqueia o arquivo para outros participantes durante a execução do bloco.

Coordenação em lote — para operações envolvendo múltiplos arquivos, a coordenação em lote é usada. O coordenador bloqueia atomicamente todos os arquivos especificados, executa a operação e libera os bloqueios. Isto é criticamente importante ao mover ou copiar conjuntos de documentos.

Exemplo de implementação

Vamos criar uma classe DocumentPresenter que implementa o protocolo NSFilePresenter e rastreia alterações em um arquivo de documento. A classe contém uma referência ao arquivo, dados internos e uma flag de validade.

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) {
        // Processamento de dados do documento
    }
}

A classe implementa presentedItemDidChange para recarregar dados quando o arquivo muda e accommodatePresentedItemDeletion para salvar o estado antes da exclusão. A fila de operações garante que todas as notificações sejam processadas sequencialmente.

O registro do apresentador é feito através de NSFileCoordinator.addFilePresenter ao abrir um documento. É importante passar as opções de leitura corretas ao coordenador — withoutChanges para operações sem modificação ou immediatelyAvailable para cenários que exigem acesso imediato.

Erros comuns

O primeiro erro comum é a falta de implementação de presentedItemOperationQueue. Se você não especificar uma fila, as notificações podem chegar em uma thread arbitrária, causando condições de corrida. Sempre use uma OperationQueue sequencial para processar notificações.

O segundo erro é bloquear nos métodos do apresentador. Os métodos do protocolo são chamados síncronamente a partir do coordenador. Se o apresentador realiza uma operação longa (escrita em BD, requisição de rede), ele bloqueia o coordenador para todos os outros participantes. Mova operações pesadas para filas em segundo plano.

O terceiro erro é ignorar accommodatePresentedItemDeletion. Se o apresentador não implementa este método e não retorna um erro, o arquivo pode ser excluído sem salvar o estado atual. Sempre salve os dados neste método se eles ainda não foram escritos no disco.

O quarto erro é a coordenação cíclica. Quando o apresentador dentro de um método de notificação chama o coordenador novamente para o mesmo arquivo, ocorre um deadlock. Verifique a flag isCoordinatedOperation antes de iniciar a coordenação dentro de um manipulador.