NSFilePresenter : qu’est-ce que c’est, protocole NSFileCoordinator et méthodes de suivi

Qu’est-ce que NSFilePresenter ?

NSFilePresenter est un protocole Foundation conçu pour suivre les modifications de fichiers et de répertoires dans les systèmes d’exploitation Apple. Le protocole définit un ensemble de méthodes que l’objet observateur implémente pour recevoir des notifications d’événements du système de fichiers.

L’objectif principal du protocole est de fournir un accès sécurisé aux fichiers dans des scénarios multithread. Dans iOS et macOS, plusieurs processus et threads peuvent accéder simultanément au même fichier via NSFileCoordinator, et NSFilePresenter garantit que chaque participant reçoit l’état de données le plus récent.

Le protocole est inclus dans Foundation depuis iOS 5.0 et macOS 10.7. Il est utilisé dans les applications travaillant avec des documents, des bases de données et tout fichier pouvant être modifié simultanément depuis différentes sources — par exemple, lors de la synchronisation iCloud ou de l’édition collaborative.

Où NSFilePresenter est utilisé

Applications basées sur des documents — le principal domaine d’utilisation de NSFilePresenter. Les applications qui fonctionnent avec UIDocument ou NSDocument s’enregistrent automatiquement comme présentateurs via NSFileCoordinator. Cela permet de gérer correctement les conflits lors de l’édition du même fichier depuis plusieurs fenêtres ou appareils.

Synchronisation iCloud — le deuxième scénario clé. Lorsqu’un fichier est modifié sur un appareil, iCloud le synchronise sur tous les appareils connectés. NSFilePresenter notifie l’application de ces changements, permettant une mise à jour opportune de l’interface.

Éditeurs multithread — le troisième scénario. Dans les applications où les files d’attente en arrière-plan chargent et sauvegardent les données simultanément avec le travail de l’utilisateur, NSFilePresenter empêche les conditions de concurrence lors de l’écriture et de la lecture de fichiers.

Comment fonctionne NSFilePresenter ?

Le mécanisme de fonctionnement de NSFilePresenter est basé sur le modèle de délégation : l’objet implémente les méthodes du protocole, s’enregistre via NSFileCoordinator et reçoit des appels chaque fois que le fichier suivi change. Le système lui-même détermine quand un changement se produit et quelles méthodes invoquer.

Le processus commence lorsque l’objet crée une instance de NSFileCoordinator et appelle la méthode du coordinateur, en passant l’URL du fichier. Le coordinateur vérifie si des présentateurs sont enregistrés pour cette URL. Si oui, il bloque l’accès en lecture ou écriture et notifie les présentateurs du changement imminent via les méthodes du protocole.

Après la fin de l’opération, le coordinateur libère le verrou et appelle les notifications finales. Il est important de noter que le présentateur ne contrôle pas le flux d’exécution — il réagit seulement aux événements. NSFileCoordinator est entièrement responsable de la coordination.

Cycle de vie de la notification

Phase de préparation — avant d’exécuter une opération, le coordinateur appelle accommodatePresentedItemDeletion ou accommodatePresentedSubitemDeletion. Le présentateur peut gérer la situation ou annuler l’opération en retournant une erreur. Cette phase permet à l’application de terminer correctement le travail avec le fichier avant qu’il ne soit modifié.

Phase de notification — après la fin de l’opération, le coordinateur appelle presentedItemDidChange ou presentedSubitemDidChange. Le présentateur reçoit un signal indiquant que le fichier a changé et peut relire son contenu. Pour le déplacement de fichier, presentedItemDidMoveToURL est appelé avec le nouvel emplacement.

Phase de finalisation — le coordinateur libère tous les verrous et ressources. Le présentateur peut continuer à travailler avec les données mises à jour. Les trois phases s’exécutent de manière synchrone dans un seul thread, donc les méthodes du protocole doivent s’exécuter rapidement sans opérations d’E/S longues.

Méthodes principales du protocole

Le protocole NSFilePresenter contient plusieurs méthodes obligatoires et optionnelles. La seule propriété obligatoire est presentedItemURL, qui retourne l’URL du fichier ou du répertoire suivi. Sans cette propriété, l’objet ne peut pas être enregistré comme présentateur.

Méthodes obligatoires

presentedItemURL — une propriété de type URL? qui doit retourner le chemin vers le fichier suivi. Si l’objet suit plusieurs fichiers, la propriété retourne l’URL de l’élément principal. Pour les répertoires, elle retourne l’URL du répertoire.

presentedItemDidChange — appelé après que le contenu du fichier suivi a changé. Dans cette méthode, le présentateur met à jour son état interne et recharge les données. Cette méthode ne reçoit pas d’informations sur ce qui a exactement changé — seulement le fait du changement.

Méthodes optionnelles

accommodatePresentedItemDeletion — appelé avant la suppression du fichier. Le présentateur peut sauvegarder l’état actuel, fermer les descripteurs de fichier ou annuler l’opération en retournant une NSError. Si la méthode retourne une erreur, l’opération de suppression n’est pas exécutée.

presentedItemDidMoveToURL — appelé après le déplacement ou le renommage du fichier. La méthode reçoit la nouvelle URL, et le présentateur doit mettre à jour la référence du fichier. Sans implémentation de cette méthode, le présentateur continuera à pointer vers l’ancien chemin inexistant.

NSFilePresenter et NSFileCoordinator

NSFileCoordinator et NSFilePresenter sont une paire indissociable. NSFileCoordinator gère l’accès aux fichiers et appelle les méthodes du présentateur. Le présentateur ne travaille pas directement avec le système de fichiers — toutes les opérations passent par le coordinateur, qui garantit l’atomicité des modifications.

Le coordinateur enregistre le présentateur via la méthode addFilePresenter de la classe NSFileCoordinator. Après l’enregistrement, le présentateur commence à recevoir des notifications. La suppression se fait via removeFilePresenter. Le système maintient une référence faible au présentateur, donc l’objet doit rester vivant pendant toute la période de suivi.

Selon Apple WWDC 2022, NSFileCoordinator utilise un mécanisme de coordination au niveau du noyau, garantissant une latence minimale lors des verrouillages. Dans les versions récentes d’iOS, le coordinateur est optimisé pour fonctionner avec Sandbox et les extensions d’application.

Règles de coordination

Intention — chaque opération de lecture ou d’écriture doit être encapsulée dans un bloc de coordination : lecture via coordinateReadingItemAtURL, écriture via coordinateWritingItemAtURL. Le coordinateur verrouille automatiquement le fichier pour les autres participants pendant l’exécution du bloc.

Coordination par lots — pour les opérations impliquant plusieurs fichiers, la coordination par lots est utilisée. Le coordinateur verrouille atomiquement tous les fichiers spécifiés, exécute l’opération et libère les verrous. Ceci est particulièrement important lors du déplacement ou de la copie d’ensembles de documents.

Exemple d’implémentation

Créons une classe DocumentPresenter qui implémente le protocole NSFilePresenter et suit les modifications d’un fichier document. La classe contient une référence au fichier, des données internes et un indicateur de validité.

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) {
        // Traitement des données du document
    }
}

La classe implémente presentedItemDidChange pour recharger les données lorsque le fichier change et accommodatePresentedItemDeletion pour sauvegarder l’état avant la suppression. La file d’attente d’opérations garantit que toutes les notifications sont traitées séquentiellement.

L’enregistrement du présentateur se fait via NSFileCoordinator.addFilePresenter lors de l’ouverture d’un document. Il est important de passer les options de lecture correctes au coordinateur — withoutChanges pour les opérations sans modification ou immediatelyAvailable pour les scénarios nécessitant un accès immédiat.

Erreurs courantes

La première erreur courante est l’absence d’implémentation de presentedItemOperationQueue. Si vous ne spécifiez pas de file d’attente, les notifications peuvent arriver sur un thread arbitraire, provoquant des courses de données. Utilisez toujours une OperationQueue sérielle pour traiter les notifications.

La deuxième erreur est le blocage dans les méthodes du présentateur. Les méthodes du protocole sont appelées de manière synchrone depuis le coordinateur. Si le présentateur effectue une opération longue (écriture BD, requête réseau), il bloque le coordinateur pour tous les autres participants. Déplacez les opérations lourdes dans des files d’attente en arrière-plan.

La troisième erreur est l’ignorance de accommodatePresentedItemDeletion. Si le présentateur n’implémente pas cette méthode et ne retourne pas d’erreur, le fichier peut être supprimé sans sauvegarder l’état actuel. Sauvegardez toujours les données dans cette méthode si elles ne sont pas encore écrites sur le disque.

La quatrième erreur est la coordination cyclique. Lorsque le présentateur à l’intérieur d’une méthode de notification appelle à nouveau le coordinateur pour le même fichier, un deadlock se produit. Vérifiez le drapeau isCoordinatedOperation avant de lancer une coordination à l’intérieur d’un gestionnaire.