NSFilePresenter: co to je, protokol NSFileCoordinator a metody sledování

Co je NSFilePresenter?

NSFilePresenter — je protokol Foundation určený pro sledování změn souborů a adresářů v operačních systémech Apple. Protokol definuje sadu metod, které objekt pozorovatele implementuje pro příjem oznámení o událostech souborového systému.

Hlavním úkolem protokolu je zajistit bezpečný přístup k souborům ve vícevláknových scénářích. V iOS a macOS může několik procesů a vláken současně přistupovat ke stejnému souboru prostřednictvím NSFileCoordinator a NSFilePresenter zaručuje, že každý účastník obdrží aktuální stav dat.

Protokol je součástí Foundation od iOS 5.0 a macOS 10.7. Používá se v aplikacích pracujících s dokumenty, databázemi a jakýmikoli soubory, které mohou být současně měněny z různých zdrojů — například při synchronizaci přes iCloud nebo při společném editování.

Kde se NSFilePresenter používá

Dokumentově orientované aplikace — hlavní oblast použití NSFilePresenter. Aplikace pracující s UIDocument nebo NSDocument se automaticky registrují jako prezentující prostřednictvím NSFileCoordinator. To umožňuje správně zpracovávat konflikty při editaci stejného souboru z více oken nebo zařízení.

Synchronizace iCloud — druhý klíčový scénář. Když se soubor změní na jednom zařízení, iCloud jej synchronizuje na všech připojených zařízeních. NSFilePresenter informuje aplikaci o těchto změnách a umožňuje včasnou aktualizaci rozhraní.

Vícevláknové editory — třetí scénář. V aplikacích, kde fronty na pozadí načítají a ukládají data současně s prací uživatele, NSFilePresenter zabraňuje stavům závodu při zápisu a čtení souborů.

Jak NSFilePresenter funguje?

Mechanismus fungování NSFilePresenter je založen na modelu delegování: objekt implementuje metody protokolu, registruje se prostřednictvím NSFileCoordinator a přijímá volání při každé změně sledovaného souboru. Systém sám určuje, kdy došlo ke změně a které metody je třeba volat.

Proces začíná vytvořením instance NSFileCoordinator objektem a voláním metody koordinátora s předáním URL souboru. Koordinátor zkontroluje, zda jsou pro toto URL registrováni nějací prezentující. Pokud ano, zablokuje přístup pro čtení nebo zápis a informuje prezentující o blížící se změně prostřednictvím metod protokolu.

Po dokončení operace koordinátor odstraní blokování a zavolá konečná oznámení. Důležité je, že prezentující neřídí tok provádění — pouze reaguje na události. Za koordinaci plně odpovídá NSFileCoordinator.

Životní cyklus oznámení

Fáze přípravy — před provedením operace koordinátor volá metodu accommodatePresentedItemDeletion nebo accommodatePresentedSubitemDeletion. Prezentující může situaci zpracovat nebo operaci zrušit vrácením chyby. Tato fáze umožňuje aplikaci řádně dokončit práci se souborem před jeho změnou.

Fáze oznámení — po dokončení operace koordinátor volá presentedItemDidChange nebo presentedSubitemDidChange. Prezentující obdrží signál, že se soubor změnil, a může znovu načíst jeho obsah. Pro přesun souboru se volá presentedItemDidMoveToURL s novým umístěním.

Fáze dokončení — koordinátor odstraní všechna blokování a uvolní prostředky. Prezentující může pokračovat v práci s aktualizovanými daty. Všechny tři fáze se provádějí synchronně v jednom vlákně, proto musí metody protokolu pracovat rychle, bez dlouhých vstupně-výstupních operací.

Hlavní metody protokolu

Protokol NSFilePresenter obsahuje několik povinných a volitelných metod. Jedinou povinnou vlastností je presentedItemURL, vracející URL sledovaného souboru nebo adresáře. Bez této vlastnosti nemůže být objekt registrován jako prezentující.

Povinné metody

presentedItemURL — vlastnost typu URL?, která musí vrátit cestu ke sledovanému souboru. Pokud objekt sleduje více souborů, vlastnost vrací URL hlavního prvku. Pro adresáře se vrací URL samotného adresáře.

presentedItemDidChange — volá se po změně obsahu sledovaného souboru. V této metodě prezentující aktualizuje svůj vnitřní stav a znovu načítá data. Tato metoda nepřijímá informace o tom, co se přesně změnilo — pouze fakt změny.

Volitelné metody

accommodatePresentedItemDeletion — volá se před odstraněním souboru. Prezentující může uložit aktuální stav, zavřít deskriptory souborů nebo zrušit operaci vrácením NSError. Pokud metoda vrátí chybu, operace odstranění se neprovede.

presentedItemDidMoveToURL — volá se po přesunu nebo přejmenování souboru. Metoda obdrží nové URL a prezentující musí aktualizovat odkaz na soubor. Bez implementace této metody bude prezentující nadále ukazovat na starou, neexistující cestu.

NSFilePresenter a NSFileCoordinator

NSFileCoordinator a NSFilePresenter — nerozlučná dvojice. NSFileCoordinator spravuje přístup k souborům a volá metody prezentujícího. Prezentující nepracuje přímo se souborovým systémem — všechny operace probíhají prostřednictvím koordinátora, který zaručuje atomicitu změn.

Koordinátor registruje prezentujícího prostřednictvím metody addFilePresenter třídy NSFileCoordinator. Po přidání začne prezentující přijímat oznámení. Odstranění se provádí prostřednictvím removeFilePresenter. Systém uchovává slabý odkaz na prezentujícího, proto musí objekt zůstat živý po celou dobu sledování.

Podle Apple WWDC 2022 používá NSFileCoordinator koordinační mechanismus na úrovni jádra, což zajišťuje minimální zpoždění při blokování. V nejnovějších verzích iOS je koordinátor optimalizován pro práci s Sandbox a rozšířeními aplikací.

Pravidla koordinace

Intention — každá operace čtení nebo zápisu musí být zabalena do koordinačního bloku: čtení prostřednictvím coordinateReadingItemAtURL, zápis prostřednictvím coordinateWritingItemAtURL. Koordinátor automaticky blokuje soubor pro ostatní účastníky po dobu provádění bloku.

Dávková koordinace — pro operace s více soubory se používá dávková koordinace. Koordinátor atomicky blokuje všechny určené soubory, provede operaci a odstraní blokování. To je kriticky důležité při přesouvání nebo kopírování sad dokumentů.

Příklad implementace NSFilePresenter

Vytvořme třídu DocumentPresenter, která implementuje protokol NSFilePresenter a sleduje změny souboru dokumentu. Třída obsahuje odkaz na soubor, interní data a příznak aktuálnosti.

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) {
        // Zpracování dat dokumentu
    }
}

Třída implementuje presentedItemDidChange pro opětovné načtení dat při změně souboru a accommodatePresentedItemDeletion pro uložení stavu před odstraněním. Operační fronta zaručuje, že všechna oznámení jsou zpracovávána sekvenčně.

Registrace prezentujícího se provádí prostřednictvím NSFileCoordinator.addFilePresenter při otevření dokumentu. Důležité je předat koordinátorovi správné možnosti čtení — withoutChanges pro operace bez úpravy nebo immediatelyAvailable pro scénáře s okamžitým přístupem.

Typické chyby při práci

První častá chyba — chybějící implementace presentedItemOperationQueue. Pokud neurčíte frontu, oznámení mohou přicházet v libovolném vlákně, což způsobuje závod dat. Vždy používejte sekvenční OperationQueue pro zpracování oznámení.

Druhá chyba — blokování v metodách prezentujícího. Metody protokolu jsou volány synchronně z koordinátora. Pokud prezentující provádí dlouhou operaci (zápis do databáze, síťový požadavek), blokuje koordinátora pro všechny ostatní účastníky. Přesuňte těžké operace do front na pozadí.

Třetí chyba — ignorování accommodatePresentedItemDeletion. Pokud prezentující neimplementuje tuto metodu a nevrací chybu, soubor může být odstraněn bez uložení aktuálního stavu. Vždy ukládejte data v této metodě, pokud ještě nebyla zapsána na disk.

Čtvrtá chyba — cyklická koordinace. Když prezentující uvnitř metody oznámení znovu zavolá koordinátora pro stejný soubor, vznikne deadlock. Zkontrolujte příznak isCoordinatedOperation před spuštěním koordinace uvnitř handleru.