coordinate(with:queue:byAccessor:)

func coordinate(with intents: [NSFileAccessIntent], 
          queue: OperationQueue, 
     byAccessor accessor: @escaping (Error?) -> Void)

Discussion 議論

This method lets you asynchronously perform coordinated read or writes. You can specify any combination of individual read or write operations. The file coordinator waits asynchronously to get access to the files and then invokes the accessor block on the specified queue. このメソッドは、あなたに協調読み出しおよび書き込みを非同期に実行させます。あなたは、何らかの連携読み出しまたは書き込み演算を指定できます。ファイルコーディネータは、非同期にファイルへのアクセスを取得するため待機します、それからアクセッサブロックを指定されたキュー上で発動します。

If an error occurs while waiting for access, an error message is passed to the block. You must check the block’s error parameter before accessing any of the files. If the error parameter is set to nil, you can freely perform the read and write operations described by your intents. Otherwise, you may not access the files. アクセスするために待機している間にエラーが発生するならば、エラーメッセージがそのブロックに渡されます。あなたは、ブロックの持つエラーパラメータを何らかのファイルにアクセスする前に確認しなければなりません。エラーパラメータがnilに設定されるならば、あなたは自由にあなたのインテントによって記述される読み出しおよび書き出し演算を実行できます。そうでなければ、あなたはファイルにアクセスしないでください。

Additionally, always use the URL property of your intent objects when accessing the files inside the accessor block. The system updates this property to account for any changes to the underlying files. For example, if the files are moved or renamed, the system updates this URL property to match. 加えて、常にあなたのインテントオブジェクトのURLプロパティを使ってください、アクセッサブロック内のファイルにアクセスする時は。システムは、このプロパティを更新することで、基礎をなすファイルへのあらゆる変更に対して説明します。例えば、ファイルが移動または名前変更されるならば、システムはこのURLプロパティを合致するように更新します。

Your file coordinator has access to the files only until the accessor block returns. Do not dispatch tasks that continue to access these files onto other threads or queues. That can cause your app to access the files outside of file coordination, and could result in data corruption or data loss. あなたのファイルコーデネータは、ただアクセッサブロックが戻るまでだけ、ファイルへのアクセスを持ちます。それらファイルにアクセスを継続するタスクを他のスレッドやキュー上へと発送（ディスパッチ）しないでください。それは、あなたのアプリにファイル協調の外側でそれらファイルにアクセスさせる原因となる可能性があり、そしてデータ汚染またはデータ消失という結果になりえます。

In general, coordinated-read operations wait for coordinated-write operations on the same URL. Coordinated-write operations wait for both coordinated-read and coordinated-write operations on the same URL. Multiple coordinated reads can occur simultaneously without blocking each other. 一般的に、協調読み出し演算は、協調書き込み演算に対して同じURL上で待機します。協調書き込み演算は、協調読み出しおよび協調書き込み演算の両方に対して同じURL上で待機します。複数の協調書き込みは、相互に遮断することなく同時に発生可能です。

Performing a coordinated read or coordinated write on the contents of a file package is treated as a coordinated read or write to the package as a whole. In general, coordinated access to a directory that is not a file package is not affected by coordinated access to the directory’s contents. Similarly, accessing the contents does not affect the directory. However, if you make a coordinated write operation using the forDeleting, forMoving, or forReplacing options, all coordinated access to the directory and its contents interact as if they were accessing the same URL. 協調読み出しまたは協調書き込みをファイルパッケージの内容の上で実行することは、そのパッケージ全体としてへの協調読み出しまたは書き込みとして扱われます。一般的に、ファイルパッケージではないディレクトリへの協調アクセスは、そのディレクトリの持つ内容への協調アクセスによって影響を被りません。同様に、内容それらにアクセスすることは、そのディレクトリに影響しません。しかしながら、あなたが協調書き込み演算をforDeleting、forMoving、またはforReplacingオプションを使ってするならば、ディレクトリおよびそれの内容への協調アクセスの全ては、まるでそれらが同じURLにアクセスしたかのように互いに影響します。

Coordinated reads and writes from the same file coordinator instance never block each other. However, if you make multiple, concurrent calls to coordinate(with:queue:byAccessor:), you risk deadlocking with another process that is similarly making multiple concurrent calls to its file coordinator. Wherever possible, invoke coordinate(with:queue:byAccessor:) once, passing in multiple file access intent objects. 同じ協調インスタンスからの協調読み出しと書き込みは、決して互いに遮断しません。しかしながら、あなたが複数の、同時発生する呼び出しをcoordinate(with:queue:byAccessor:)にするならば、あなたは同様に複数の同時発生する呼び出しをそれのファイルコーディネータにする別のプロセスと膠着状態になる危険があります。可能ならどこであれ、一旦coordinate(with:queue:byAccessor:)を、複数のファイルアクセスインテントオブジェクトを渡して発動してください。

Coordinated-read and -write operations also wait on any file presenters methods that are triggered as part of the coordinated access. Coordinated access triggers method calls on all the file presenters for the same URL—even on file presenters in other processes. There is only one exception: file coordinator never sends messages to the file presenter that was passed to its init(filePresenter:) method. 協調読み出しおよび書き込み演算はまた、協調アクセスの一部として引き起こされるあらゆるファイルプレゼンタメソッドに関して待機します。協調アクセスは、同じURLに対する全てのファイルプレゼンタ上でメソッド呼び出しを引き起こします — 他のプロセスの中のファイルプレゼンタ上でさえもです。唯一の例外があります：ファイルコーディネータは、それのinit(filePresenter:)メソッドに渡されたファイルプレゼンタに、決してメッセージを送りません。

Coordinated reads trigger the following method calls: 協調読み出しは以下のメソッド呼び出しを引き起こします：

• The relinquishPresentedItem(toReader:) method is called. relinquishPresentedItem(toReader:)メソッドが呼び出されます。

• If the withoutChanges option is not used then savePresentedItemChanges(completionHandler:) is called. withoutChangesオプションが使われないならば、そのときsavePresentedItemChanges(completionHandler:)が呼び出されます。

• If the file or directory is part of a file package, these methods are also called on the package’s file presenter. If there are nested packages, the methods are called on all the packages’ file presenters. ファイルまたはディレクトリがファイルパッケージの一部ならば、これらメソッドはまたそのパッケージの持つファイルプレゼンタ上でも呼び出されます。入れ子にされたパッケージがあるならば、メソッドそれらは全てのパッケージのファイルプレゼンタ上で呼び出されます。

Coordinated writes trigger the following method calls: 協調書き込みは以下のメソッド呼び出しを引き起こします：

• The relinquishPresentedItem(toWriter:) method is called. If the target is part of a file package, the method is called on the package’s presenter, just like in coordinated reads. relinquishPresentedItem(toWriter:)メソッドが呼び出されます。ターゲットがファイルパッケージの一部ならば、メソッドはパッケージの持つプレゼンタ上で呼び出されます、ちょうど協調読み出しでのように。

• If the target is a directory and the forDeleting, forMoving, or forReplacing options are used, relinquishPresentedItem(toWriter:) is also called on all the file presenters for the directory’s contents. ターゲットがディレクトリであるそしてforDeleting, forMoving、またはforReplacingオプションが使われるならば、relinquishPresentedItem(toWriter:)もまたそのディレクトリの持つ内容それらに対するファイルプレゼンタの全てで呼び出されます。

• If the forDeleting or forReplacing options are used, the accommodatePresentedItemDeletion(completionHandler:) method is called. If the target is a directory, that method is called on the file presenters for the directory’s contents as well. If the target is inside a file package, the accommodatePresentedSubitemDeletion(at:completionHandler:) method is called on the package’s presenter. ターゲットがディレクトリならば、そのメソッドはディレクトリの持つ内容に対するファイルプレゼンタそれらの上で同様に呼び出されます。ターゲットがファイルパッケージ内ならば、accommodatePresentedSubitemDeletion(at:completionHandler:)メソッドがそのパッケージの持つプレゼンタ上で呼び出されます。

• If the forReplacing option is used, the definition of the target file or directory can vary depending on how this write operation interacts with other coordinated write operations. For more details, see forReplacing. forReplacingオプションが使われるならば、ターゲットのファイルまたはディレクトリの定義は、この書き込み演算がどのように他の協調書き込み演算と相互作用するかに依存して変化することがあります。詳細として、forReplacingを見てください。

• if the forMerging option is used, the savePresentedItemChanges(completionHandler:) method is called. If the target is part of a file package, the method is called on the package’s presenter, just as with coordinated reads. forMergingオプションが使われるならば、savePresentedItemChanges(completionHandler:)メソッドが呼び出されます。ターゲットがファイルパッケージの一部ならば、メソッドはパッケージの持つプレゼンタ上で呼び出されます、ちょうど協調読み出しと同様に。

For both reading and writing, if there are multiple file presenters involved, the order in which the methods are called is undefined. If any of the file presenters signal an error, the coordinated access fails and the error is passed to the accessor block. 読み出しと書き込みの両方に対して、関係する複数のファイルプレゼンタがあるならば、メソッドが呼び出される順番は未定義です。ファイルプレゼンタのどれかがエラーを合図するならば、協調アクセスは失敗します、そしてエラーはアクセッサブロックへと渡されます。