NSFileCoordinator class coordinates the reading and writing of files and directories among multiple processes and objects in the same process. You use instances of this class as is to read from, write to, modify the attributes of, change the location of, or delete a file or directory, but before your code to perform those actions executes, the file coordinator lets registered file presenter objects perform any tasks that they might require to ensure their own integrity. For example, if you want to change the location of a file, other objects interested in that file need to know where you intend to move it so that they can update their references.
- iOS 5.0+
- macOS 10.7+
- tvOS 5.0+
- watchOS 2.0+
Objects that adopt the
NSFilePresenter protocol must register themselves with the
NSFileCoordinator class to be notified of any pending changes. They do this by calling the
addFilePresenter(_:) class method. A file presenter must balance calls to
addFilePresenter(_:) with a call to
removeFilePresenter(_:) before being released, even in a garbage-collected application. The file presenter class maintains a list of active file presenter objects in the current application and uses that list, plus the file coordinator classes in other processes, to deliver notifications to all of the objects interested in a particular item.
NSFileCoordinator are meant to be used on a per-file-operation basis, where a file operation is something like opening and reading the contents of a file or moving a batch of files and directories to a new location. There is no benefit to keeping a file coordinator object past the length of the planned operation. In fact, because file coordinators retain file presenter objects, keeping one around could prevent the file presenter objects from being released in a timely manner.
For information about implementing a file presenter object to receive file-related notifications, see
File Presenters and iOS
If your app or extension enters the background with an active file presenter, it may be terminated by the system in order to prevent deadlock on that file. To prevent this situation, call
removeFilePresenter(_:) to remove the file presenter in the
applicationDidEnterBackground(_:) method or in response to a
UIApplicationDidEnterBackground notification. Call
addFilePresenter(_:) to add the file presenter again in the
applicationWillEnterForeground(_:) method or in response to a
File Coordinators and iOS
A coordinated read or write will automatically begin a background task when granted, similar to one created with the
beginBackgroundTask(expirationHandler:) method. This helps ensure that your app or extension has sufficient time to finish the read or write operation if it’s suspended, without creating a deadlock on access to that file by other processes. If a process is suspended while waiting for a coordinated read or write to be granted, the request is canceled, and an
NSError object with the code
NSUserCancelledError is produced. If the background task expires, the process is terminated.
Each file coordinator object you create should be used on a single thread only. If you need to coordinate file operations across multiple objects in different threads, each object should create its own file coordinator.