GCDReference


グランドセントラルディスパッチ(GCD) は、言語機能、実行時ライブラリ、および iOS と OS X のマルチコアハードウェア上の同時コード実行のためのサポートに対するシステミックな、総合的な改善を提供する、システムの機能強化を含みます。


BSD サブシステム、CoreFoundation、および Cocoa の API はすべて、より効率的に、かつ改善された応答性を備えたシステムとアプリケーションを、より高速に実行するように両方を補助するためにこれらの拡張機能を使用するように拡張されています。効果的に複数のコアを使用し、ましてやコンピューティングコア数の異なる、またはそれらのコアが競合する複数のアプリケーションが存在する環境で別のコンピュータでそれをする 1 つのアプリケーションがいかに難しいか考えてみましょう。GCD は、システム・レベルで動作し、より良いバランスの取れた方法で利用可能なシステムリソースに合わせ、実行中のすべてのアプリケーションのニーズに対応できます。


このドキュメントは、システムの Unix レベルでの操作の非同期実行をサポートする、GCD の API について説明します。ファイルディスクリプタ、Mach ポート、シグナル、またはタイマーとの対話を管理するには、この API を使用できます。OS X v10.7 以降ではまた、ファイル記述子の汎用非同期の I/O 操作を処理するために GCD を使用できます。


GCD は、システム・レベルのアプリケーションに限定されるものではなく、より高いレベルのアプリケーションのためにそれを使用する前に、(NSOperation とブロックオブジェクトを経由して) Cocoa で提供された同様の機能が、あなたのニーズに合わせて使いやすく、またより適切かどうかを検討する必要があります。詳細については、同時実行プログラミング・ガイド を参照してください。



重要： fork システムコールで GCD を混合する際は注意してください。プロセスが fork を呼び出す前に GCD の呼び出しを行う場合、exec か、関連する関数の呼び出しに成功する後まで、得られた子プロセスで追加の GCD 呼び出しを行うのは安全ではありません。


GGCD オブジェクトと自動参照カウント


Objective-C のコンパイラを使用してアプリをビルドする時、すべてのディスパッチオブジェクトは、Objective-C のオブジェクトです。自動参照カウント(ARC) が有効になっている場合、このように、ディスパッチオブジェクトが保持されていて、その他すべての Objective-C のオブジェクトと同じように自動的に解放されます。ARC が有効でない場合、保持し、あなたのディスパッチオブジェクトを解放する dispatch_retain と dispatch_release 関数(または Objective-C の意味) を使用して下さい。Core Foundation の保持／リリース関数を使用することはできません。


(既存のコードとの互換性を維持するために) 今後の展開のターゲットと ARC を有効にされたアプリで保持／リリースの意味を使用する必要がある場合、コンパイラフラグに -DOS_OBJECT_USE_OBJC=0 を追加して、Objective-C に基づくディスパッチオブジェクトを無効にできます。


関数


キュー(待ち行列)の作成と管理


アプリケーションのメインスレッドに関連付けられているシリアルディスパッチキューを返します。


宣言

dispatch_queue_t dispatch_get_main_queue(void);


戻り値

メインキューを返します。main が呼び出される前に、このキューは、メインスレッドに代わって自動的に作成されます。


議論

メインキューは、システムによって自動的に作成され、アプリケーションのメインスレッドに関連付けられます。アプリケーションはメインキューに提出されたブロックを起動するには、以下の 3 つのアプローチの 1つ(1つのみ) を使用します。


グローバルの同時キューと同じように、dispatch_suspend、dispatch_resume、dispatch_set_context、及び似たものはこの関数によって返されたキューで使用する場合、何の効果もありません。


利用可能




サービスクラスの指定された品質を持つシステムに定義されたグローバルの同時キューを返します。


宣言

dispatch_queue_t dispatch_get_global_queue( long identifier, unsigned long flags);


パラメーター

identifierタスクを与えたいサービスの品質はこのキューを使用して実行されます。サービスの品質は、キューによって実行されるタスクに与えられた優先度を決定するのに役立ちます。値QOS_CLASS_USER_INTERACTIVE、QOS_CLASS_USER_INITIATED、QOS_CLASS_UTILITY、または QOS_CLASS_BACKGROUND を指定できます。ユーザ対話型の、またはユーザーが開始したタスクを処理するキューは、バックグラウンドで実行することを意味するタスクよりも高い優先度を持っています。

また dispatch_queue_priority_t で見られる、ディスパッチキューの優先順値のいずれか一つを指定することもできます。これらの値は、適切なサービスの品質クラスにマッピングされます。
flags将来の使用のために予約されているフラグ。常にこのパラメータには 0 を指定します。

戻り値

要求されたグローバルの同時キュー。


議論

この関数は、指定されたサービスの品質レベルでタスクを実行するのに適したキューを返します。dispatch_suspend、dispatch_resume への呼び出し、および dispatch_set_context 関数は返されたキューに影響を与えません。


返されたキューに亭主すされたタスクは、互いに対して同時にスケジュールされています。




ブロックが提出可能な新たなディスパッチキューを作成します。


宣言

dispatch_queue_t dispatch_queue_create( const char *label dispatch_queue_attr_t attr);


パラメーター

labelインスツルメント、sample、スタックショット、およびクラッシュレポートのようなデバッグツールにそれを唯一識別するためにキューに接続する文字列ラベル。アプリケーション、ライブラリ、およびフレームワークは、すべて独自のディスパッチキューを作成できますので、逆 DNS 命名スタイル(com.example.myqueue) が推奨されます。このパラメータはオプションであり、NULL にすることができます。
attrOS X v10.7 以降で、または iOS 4.3 以降では、シリアルキューを作成または特に同時キューを作成するのに DISPATCH_QUEUE_CONCURRENT を指定する DISPATCH_QUEUE_SERIAL(または NULL) を指定します。以前のバージョンでは、このパラメータに NULL を指定しなければなりません。

戻り値

新たに作成されたディスパッチキュー。


議論

シリアルキューに提出されたブロックは FIFO 順で一度に 1 つずつ実行されます。しかし、独立したキューに提出されたブロックは互いに対して同時に実行されてもよいことに注意してください。同時のキューに提出されたブロックは FIFO 順にデキューされますが、リソースがそうするために利用可能である場合は、同時に実行できます。


アプリケーションがもはやディスパッチキューを必要としない場合、dispatch_release 関数でそれを解放するべきです。キュー提出保留中のブロックは、そのキューへの参照を保持するので、保留中のすべてのブロックが完了するまでキューは割り当て解除されません。




現在実行中のブロックが実行しているキューを返します。


宣言

dispatch_queue_t dispatch_get_current_queue( void);


戻り値

現在のキューを返します。


議論

この関数は決して NULL を返すことはないように定義されています。


提出されたブロックのコンテキストの外側から呼び出された場合、呼び出しがメインスレッドから実行された場合、この関数はメインキューを返します。呼び出しが他のスレッドからなされた場合、この関数は、デフォルトの同時キューを返します。




望みのサービスの品質情報でディスパッチキューを作成するのに適した属性を返します。


宣言

dispatch_queue_attr_t dispatch_queue_attr_make_with_qos_class( dispatch_queue_attr_t attr, int qos_class, int relative_priority);


パラメーター

attrキュー属性値は、サービスの品質クラスと結合されます。タスクが同時にスケジュール化できる場合は、シリアルまたは DISPATCH_QUEUE_CONCURRENT スケジュール化されるように作業を提出したい場合、DISPATCH_QUEUE_SERIAL を指定します。NULL を指定した場合、この関数は、シリアルキューを作成します。
qos_classタスクに与えたいサービスの品質はこのキューを使用して実行されます。サービス品質は、キューによって実行されるタスクに与えられた優先度を決定するのに役立ちます。QOS_CLASS_USER_INTERACTIVE、QOS_CLASS_USER_INITIATED、QOS_CLASS_UTILITY、または QOS_CLASS_BACKGROUND のいずれかの値を指定します。ユーザ対話型またはユーザーが開始したタスクを処理するキューは、バックグラウンドで実行することを意味するタスクよりも高い優先度を持っています。
relative_priority与えられたサービスの品質クラスの最大にサポートされているスケジューラの優先順位からの負のオフセット。この値は、MIN_QOS_CLASS_PRIORITY よりも大きく、0 より小さくなければなりません。

戻り値

ディスパッチキューを作成するとき dispatch_queue_create 関数に渡すことができる属性値。


議論

特定のサービスの品質レベルのディスパッチキューを作成する場合、dispatch_queue_create 関数を呼び出す前に、この関数を呼び出して下さい。この関数は、キュー・タイプの属性を、指定したサービスの品質情報と結びつけ、dispatch_queue_create 関数に渡せる値を返します。この機能を使用して、指定したサービスの品質の値は、ディスパッチキューのターゲット・キューから継承された優先度よりも優先されます。


グローバルキューの優先順位は、以下のサービスの品質クラスにマッピングします。




キューを作成したときにキューに指定されたラベルを返します。


宣言

const char * dispatch_queue_get_label(dispatch_queue_t queue);


パラメーター

queueこのパラメーターは NULL にはできません。

戻り値

キューのラベル。キューを作成するときに、アプリケーションがラベルを提供しない場合、結果を NULL にすることができます。




与えられたオブジェクトのターゲット・キューを設定します。


宣言

void dispatch_set_target_queue( dispatch_object_t object, dispatch_queue_t queue);


パラメーター

object変更すべきオブジェクト。このパラメータは NULL にはできません。
queueオブジェクトの新しいターゲット・キュー。キューは保持され、以前のものは、もしあれば、解放されます。このパラメータは NULL にはできません。

議論

オブジェクトのターゲット・キューは、オブジェクトを処理する責任があります。ターゲット・キューは、オブジェクトのファイナライザが呼び出されるキューを決定します。また、いくつかのオブジェクトのターゲット・キューを変更すると、その動作を変更します。




メインキューに提出されたブロックを実行します。


宣言

void dispatch_main( void);


戻り値

この関数は決して返しません。


議論

この関数は、メインスレッドを"停め"、ブロックがメインキューに提出されるのを待ちます。メインスレッドで UIApplicationMain (iOS)、NSApplicationMain(OS X)、または CFRunLoopRun を呼び出すアプリケーションは dispatch_main を決して呼び出してはいけません。




ディスパッチ用のキューのタスク


GCD はアプリケーションがブロックオブジェクトの形でタスクを提出できるものに FIFO キューを提供し、管理します。ディスパッチキューに提出されたブロックは、完全にシステムによって管理されるスレッドのプール上で実行されます。保証は、タスクが実行されるスレッド上と同じようになされません。GCD は、3 種類のキューを提供しています：


メインキューは、システムによって自動的に作成され、アプリケーションのメインスレッドに関連付けられます。アプリケーションがメインキューに提出したブロックを起動するには、以下の 3 つのアプローチの 1 つ(1 つのみ) を使用します。


同時に多くのタスクを実行するためには、同時キューを使用してください。GCD は自動的に 4 つの同時ディスパッチキューを作成し(iOS 5 または OS X v10.7 以前では 3 つ) それらはアプリケーションにグローバルであり、その優先順位によってのみ区別されます。アプリケーションは dispatch_get_global_queue 関数を使用して、これらのキューを要求します。これらの同時キューは、アプリケーションに対してグローバルなので、保持し、それらを解放する必要はありません。それらを保持し、解放する呼び出しは無視されます。OS X v10.7 以降または iOS 4.3 以降では、またあなた自身のコードモジュールで使用するための追加の同時キューを作成することができます。


タスクが予測可能な順序で実行することを確実にするために、シリアルキューを使用してください。これは、リソースを保護したり、キープロセスを同期させるような、各シリアルキューの特定の目的を識別するようにするとよいでしょう。アプリケーションは明示的にシリアルキューを作成し、管理する必要があります。必要に応じてそれらを多く作成できますが、ちょうど同時に多くのタスクを実行するために、同時キューの代わりにそれらを使用することは避けるべきです。



重要： GCD は、C レベルの API です。より高いレベルの言語で生成された例外はキャッチしません。あなたのアプリケーションは、ディスパッチキューに提出したブロックから戻る前に、すべての例外をキャッチしなければなりません。




ディスパッチキュー上で非同期実行するためのブロックを提出し、すぐに戻ります。


宣言

void dispatch_async( dispatch_queue_t queue, dispatch_block_t block);


パラメーター

queueその上でブロックに提出するべきキュー。ブロックが実行完了するまでキューはシステムによって保持されます。このパラメータは NULL にすることはできません。
blockターゲット・ディスパッチキューに提出すべきブロック。この関数は、呼び出し元に代わって Block_copy と Block_release を実行します。このパラメータは NULL にすることはできません。

議論

この関数は、ディスパッチキューにブロックを提出するための基本的なメカニズムです。この関数への呼び出しは常にブロックが提出された直後に戻り、ブロックが呼び出されるのを待つことは決してありません。ターゲット・キューは、ブロックが同じキューに提出される他のブロックに対して連続的にまたは同時に呼び出されているか否かを判定します。独立したシリアル・キューは、互いに対して同時に処理されます。




ディスパッチキューで非同期に実行するためのアプリケーション定義関数を提出し、すぐに戻ります。


宣言

void dispatch_async_f( dispatch_queue_t queue, void *context, dispatch_function_t work);


パラメーター

queueその上で関数を提出すべきキュー。関数が実行を実行するまでキューはシステムによって保持されます。このパラメータは NULL にすることはできません。
context関数に渡すべき、アプリケーション定義のコンテキストパラメータ。
workターゲット・キュー上で起動すべきアプリケーション定義関数。この関数に渡される最初のパラメータは、context パラメータの値です。このパラメータは NULL にすることはできません。

議論

この関数は、ディスパッチキューにアプリケーション定義関数を提出するための基本的なメカニズムです。この関数への呼び出しは常に関数が提出された直後に戻り、それが呼び出されるのを待つことはありません。ターゲット・キューは、関数が同じキューに提出された他のタスクに対して連続的にまたは同時に呼び出されているか否かを判定します。シリアル・キューは、互いに対して同時に処理されます。




ディスパッチキュー上で実行するためのブロックオブジェクトを提出し、そのブロックが完了するまで待機します。


宣言

void dispatch_sync( dispatch_queue_t queue, dispatch_block_t block);


パラメーター

queueその上にブロックを提出すべきキュー。このパラメータは NULL にすることはできません。
blockターゲットディスパッチキュー上で呼び出されるブロック。このパラメータは NULL にすることはできません。

議論

同期実行のためにディスパッチキューにブロックを提出します。dispatch_async とは異なり、ブロックが終了するまで この関数は戻りません。この関数を呼び出し、現在のキューのをターゲットにすると、行き詰まりになります。


dispatch_async とは異なり、ターゲット・キュー上で実行されるものは保持されません。この関数の呼び出しが同期するので、呼び出し側の参照を"借用します(borrow)"。しかも、Block_copy はブロック上で実行されません。


最適化の結果として、この関数は、可能な場合、現在のスレッド上のブロックを呼び出します。




ディスパッチキュー上の同期実行のためのアプリケーション定義関数を提出します。


宣言

void dispatch_sync_f( dispatch_queue_t queue, void *context, dispatch_function_t work);


パラメーター

queueその上で関数を提出すべきキュー。このパラメータは NULL にすることはできません。
context関数に渡すべきアプリケーション定義のコンテキストパラメータ。
workターゲット・キュー上で起動すべきアプリケーション定義関数。この関数に渡される最初のパラメータは、context パラメータの値です。このパラメータは NULL にすることはできません。

以下も見よ

dispatch_sync



指定した時刻に実行するためのブロックをキューにします。


宣言

void dispatch_after( dispatch_time_t when, dispatch_queue_t queue, dispatch_block_t block);


パラメーター

whendispatch_time または dispatch_walltime によって返される時間のマイルストーン。
queueその上にブロックを提出すべきキュー。ブロックの実行が完了するまでキューはシステムによって保持されます。このパラメータは NULL にすることはできません
block提出すべきブロック。この関数は、呼び出し元に代わって Block_copy と Block_release を実行します。このパラメータは NULL にすることはできません。

議論

この関数は、指定された時間まで待機してから非同期的に指定された queue に block を加えます。


when のパラメータとして DISPATCH_TIME_NOW を渡すのは、サポートされていますが、代わりに dispatch_async を呼び出すのと比べ、最適ではないです。 DISPATCH_TIME_FOREVER を渡すのは、未定義です。




指定した時刻に実行するためのアプリケーション定義関数をキューにします。


宣言

void dispatch_after_f( dispatch_time_t when, dispatch_queue_t queue, void *context, dispatch_function_t work);


パラメーター

whendispatch_time または dispatch_walltime によって返される時間のマイルストーン。
queueその上で関数を提出すべきキュー。アプリケーションの定義関数が実行を完了するまでキューはシステムによって保持されます。このパラメータは NULL にすることはできません。
context関数に渡すべき、アプリケーション定義のコンテキストパラメータ。
workターゲット・キュー上で起動すべきアプリケーション定義関数。この関数に渡される最初のパラメータは、context パラメータの値です。このパラメータは NULL にすることはできません。

議論

この関数は、指定された時間まで待機してから非同期的に指定された queue に work 関数を追加します。


when のパラメータとして DISPATCH_TIME_NOW を渡すのは、サポートされていますが、代わりに dispatch_async を呼び出すのと比べて最適ではないです。 DISPATCH_TIME_FOREVER を渡すのは、未定義です。




複数の呼び出しのディスパッチキューにブロックを提出します。


宣言

void dispatch_apply( size_t iterations, dispatch_queue_t queue, void (^block)( size_t));


宣言

iteration実行すべき反復回数。
queueその上でブロックを提出すべきキュー。このパラメータは NULL にすることはできません。
block提出されるべきアプリケーション定義の関数。このパラメータは NULL にすることはできません。

議論

この関数は、複数の呼び出しのディスパッチキューにブロックを提出し、返す前にすべてのタスクブロックの繰り返しが完了するのを待ちます。ターゲット・キューが dispatch_get_global_queue によって返される同時キューである場合は、ブロックは同時に呼び出すことができ、したがって、それは同時共有上安全でなければなりません。同時キューでこの関数を使用すると、効率的な並列の for ループとして有用です。


繰り返しの現在のインデックスは、ブロックの呼び出しのそれぞれに渡されます。




複数の呼び出しのディスパッチキューにアプリケーション定義関数を提出します。


宣言

void dispatch_apply_f( size_t iterations, dispatch_queue_t queue, void *context, void (*work)(void *, size_t));


パラメーター

iteration実行すべき反復回数。
queueその上でブロックを提出すべきキュー。このパラメータは NULL にすることはできません。
context関数に渡すべきアプリケーション定義のコンテキストパラメータ。
workターゲット・キュー上で起動すべきアプリケーション定義関数。この関数に渡される最初のパラメータは、context パラメータの値です。2 番目のパラメータは、現在の繰り返しのインデックスです。このパラメータは NULL にすることはできません。

議論

この関数は、複数の呼び出しのディスパッチキューにアプリケーション定義の関数を提出し、返す前に関数のすべての繰り返しが完了するのを待ちます。ターゲット・キューが dispatch_get_global_queue によって返される同時キューである場合は、関数は同時に呼び出すことができ、したがって、それは同時共有上安全でなければなりません。同時キューにこの関数を使用すると、効率的な並列 for ループのとして有用です。


繰り返しの現在のインデックスは、関数の呼び出しのそれぞれに渡されます。




アプリケーションの寿命中に、たった一度だけブロックオブジェクトを実行します。


宣言

void dispatch_once( dispatch_once_t *predicate, dispatch_block_t block);


パラメーター

predicateブロックが完了したか否かをテストするために使用される dispatch_once_t 構造体へのポインタ。
block一度だけ実行するブロックオブジェクト。

議論

この関数は、アプリケーションのグローバルデータ(シングルトン) の初期化のために有用です。ブロックによって初期化されるすべての変数を使用するかテストする前に、この関数を呼び出して下さい。


複数のスレッドから同時に呼び出された場合、ブロックが完了するまで、この関数は同期的に待ちます。


predicate は、グローバルまたは静的スコープに格納されている変数を指していなければなりません。(Objective-C のインスタンス変数を含む) 自動または動的な保存で predicate を使用した結果は未定義です。




アプリケーションの寿命中に、たった一度だけブロックオブジェクトを実行します。


宣言

void dispatch_once_f( dispatch_once_t *predicate, void *context, dispatch_function_t function);


パラメーター

predicateブロックが完了したか否かをテストするために使用される dispatch_once_t 構造体へのポインタ。
context関数に渡すべき、アプリケーション定義のコンテキストパラメータ。
functionターゲット・キューを一度呼び出すアプリケーション定義関数。この関数に渡されたパラメータは、context パラメータの値です。このパラメータは NULL にすることはできません。

議論

この関数は、アプリケーションのグローバルデータ(シングルトン) の初期化のために有用です。関数によって初期化されるすべての変数を使用するかテストする前に、この関数を呼び出して下さい。


複数のスレッドから同時に呼び出された場合、関数が完了するまで、この関数は同期的に待ちます。


predicate は、グローバルまたは静的スコープに格納されている変数を指していなければなりません。(Objective-C のインスタンス変数を含む) 自動または動的な保存で predicate を使用した結果は未定義です。




ディスパッチグループの使用


ブロックをグループ化すると、集計の同期を可能にします。あなたのアプリケーションは複数のブロックを提出でき、それらが異なるキュー上で実行する場合でも、それらすべてを完全に追跡できます。指定されたすべてのタスクが完了するまで進捗が行うことができないと、この動作が役立つことがあります。




ディスパッチキューにブロックを提出し、指定されたディスパッチグループとブロックを関連付けます。


宣言

void dispatch_group_async( dispatch_group_t group, dispatch_queue_t queue, dispatch_block_t block);


パラメーター

group提出されたブロックオブジェクトと関連付けられたディスパッチグループ。ブロックが実行完了するまでグループは、システムによって保持されます。このパラメータは NULL にすることはできません。
queueブロックオブジェクトが非同期呼び出しのために提出されたディスパッチキュー。ブロックが実行完了するまでキューはシステムによって保持されます。このパラメータは NULL にすることはできません。
block非同期的に実行するべきブロックオブジェクト。この関数は、呼び出し元に代わって Block_copy と Block_release を実行します。

議論

ディスパッチキューにブロックを提出し、与えられたディスパッチグループとブロックオブジェクトを関連付けます。ディスパッチグループは、それが参照するブロックオブジェクトの完了を待つために使用できます。




ディスパッチキューにアプリケーションで定義された関数を提出し、指定されたディスパッチグループに関連付けます。


宣言

void dispatch_group_async_f( dispatch_group_t group, dispatch_queue_t queue, void *context, dispatch_function_t work);


パラメーター

group提出された関数を関連付けるべきディスパッチグループ。アプリケーションで定義された関数が実行を完了するまでグループは、システムによって保持されます。このパラメータは NULL にすることはできません。
context関数が非同期呼び出しのために提出されたディスパッチキュー。アプリケーションで定義された関数が実行を完了するまでキューはシステムによって保持されます。このパラメータは NULL にすることはできません。
contextアプリケーションで定義された関数に渡すべきアプリケーションで定義された context パラメータ。
workターゲット・キュー上で起動すべきアプリケーションで定義された関数。この関数に渡される最初のパラメータは、context パラメータの値です。

議論

ディスパッチキューにアプリケーションで定義された関数を提出し、与えられたディスパッチグループにそれを関連付けます。ディスパッチグループは、それが参照するアプリケーションで定義された関数の完了を待つために使用できます。




ブロックオブジェクトが関連付けられるような新しいグループを作成します。


宣言


dispatch_group_t dispatch_group_create( void);


戻り値

新たに作成したグループ、または失敗した場合には、NULL。


議論

この関数は、ブロックオブジェクトが( dispatch_group_async 関数を使用して) 関連付けられる新たなグループを作成します。ディスパッチグループは、新しいタスクが関連付けられ、タスクが完了したときに、それを減分する場合、カウントを増分し、その卓越した関連するタスクを維持しています。dispatch_group_notify や dispatch_group_wait 使用のような関数は、グループに関連付けられているすべてのタスクが完了したときに、そのカウントを使用してアプリケーションが決定できるようにします。その時、あなたのアプリケーションは、任意の適切なアクションを取ることができます。


アプリケーションがもはやディスパッチグループを必要としない場合、それは、グループオブジェクトへの参照を解放し、そのメモリを最終的に解放する dispatch_release を呼び出すべきです。




ブロックがグループに入ったことを明示的に示します。


宣言

void dispatch_group_enter( dispatch_group_t group);


パラメーター

group更新するべきディスパッチグループ。このパラメータは NULL にすることはできません。

議論

この関数を呼び出すと、グループ内の未処理のタスクの現在のカウントを増分します。この関数を( dispatch_group_leave と共に) 使用すると、それは dispatch_group_async 関数を使用するよりも、他の手段によってグループに明示的にタスクを追加し、また削除する場合は、適切にタスクの参照カウントを管理する事をアプリケーションに可能にします。この関数への呼び出しは dispatch_group_leave への呼び出しでバランスをとらなければなりません。同時に複数のグループにブロックを関連付けるために、この機能を使用できます。




グループ内のブロックが完了したことを明示的に示します。


宣言

void dispatch_group_leave( dispatch_group_t group);


パラメーター

group更新するべきディスパッチグループ。このパラメータは NULL にすることはできません。

議論

この関数を呼び出すと、グループ内の未処理のタスクの現在のカウントを減分します。この関数を( dispatch_group_enter と共に) 使用すると、それは dispatch_group_async 関数を使用するよりも、他の手段によってグループに明示的にタスクを追加し、また削除する場合は、適切にタスクの参照カウントを管理する事をアプリケーションに可能にします。


この関数への呼び出しは dispatch_group_enter への呼び出しでバランスをとらなければなりません。dispatch_group_enter 以上の回数、呼び出すのは無効で、負の数になります




以前に提出されたブロックオブジェクトのグループが完了した時にブロックオブジェクトを、キューに提出されるようにスケジュールします。


宣言

void dispatch_group_notify( dispatch_group_t group, dispatch_queue_t queue, dispatch_block_t block);


パラメーター

group監視すべきディスパッチグループ。ブロックが実行を完了するまでグループは、システムによって保持されます。このパラメータは NULL にすることはできません。
queueグループが完了した時、その供給されたブロックが提出されるべきキュー。ブロックが実行を完了するまでキューはシステムによって保持されます。このパラメータは NULL にすることはできません。
blockグループが完了した時、提出するべきブロック。この関数は、呼び出し元に代わって Block_copy と Block_release を行います。このパラメータは NULL にすることはできません。

議論

ディスパッチグループに関連付けられたすべてのブロックが完了した時、この関数はブロックが、指定されたキューに提出するべきという通知をスケジュールします。グループが(全くブロックオブジェクトがディスパッチグループに関連付けられていない) 空の場合は、通知ブロックオブジェクトがすぐに提出されます。


通知ブロックが提出されると、グループは空になります。グループは、dispatch_release で解放されるか、または追加のブロックオブジェクトで再利用されるかどちらかです。詳細については、dispatch_group_async を参照してください。




以前に提出されたブロックオブジェクトのグループが完了した時にアプリケーションで定義された関数が、キューに提出されるようにスケジュールします。


宣言

void dispatch_group_notify_f( dispatch_group_t group, dispatch_queue_t queue, void *context, dispatch_function_t work);


パラメーター

group監視すべきディスパッチグループ。アプリケーションに定義された関数が実行を完了するまでグループは、システムによって保持されます。このパラメータは NULL にすることはできません。
queueグループが完了した時、供給されるブロックが提出されるキュー。アプリケーションに定義された関数が実行を完了するまでキューはシステムによって保持されます。このパラメータは NULL にすることはできません。
contextアプリケーションに定義された関数に渡されるべきアプリケーションに定義されたコンテキストパラメータ。
workターゲット・キュー上で起動すべきアプリケーションに定義された関数。この関数に渡される最初のパラメータは、context パラメータの値です。

議論

ディスパッチグループに関連付けられたすべてのブロックが完了したときに、この関数は、通知ブロックを、指定されたキューに提出するようにスケジュールします。グループが(全くブロックオブジェクトがディスパッチグループに関連付けられていない) 空の場合は、通知ブロックオブジェクトがすぐに提出されます。


通知ブロックが提出されると、グループは空になります。グループは、dispatch_release で解放されるか、または追加のブロックで再利用されるかどちらかです。詳細については、dispatch_group_async を参照してください。




以前に提出されたブロック・オブジェクトが完了するのを同期的に待機します。指定された終了時間が経過する前に、ブロックが完了しない場合戻ります。


宣言

long dispatch_group_wait( dispatch_group_t group, dispatch_time_t timeout);


パラメーター

groupその上で待機すべきディスパッチグループ。このパラメータは NULL にすることはできません。
timeoutタイムアウトするとき(dispatch_time を参照してください)。DISPATCH_TIME_NOW と DISPATCH_TIME_FOREVER 定数は便宜のために提供されています。

戻り値

成功した場合にはゼロを返し(指定されたタイムアウトまでに完了したグループに関連付けられたすべてのブロック) エラーの場合非ゼロ(タイムアウトが発生しました)。


議論

この関数は、与えられたディスパッチグループに関連付けられたブロックの完了を待って、すべてのブロックが完了しているか、指定したタイムアウトが経過したときのいずれかを返します。タイムアウトが発生した場合、グループは元の状態に復元されます。


ディスパッチグループが(グループに関連付けられたブロックが存在しない) 空である場合、この関数はすぐに戻ります。


この関数が正常に戻った後、ディスパッチグループは空になります。それは dispatch_release で解放することができるか、または追加のブロックで再利用できるかいずれかです。詳細については、dispatch_group_async を参照してください。




ディスパッチオブジェクトの管理


GCD は、ディスパッチオブジェクトインタフェースが、アプリケーションに、メモリ管理のような様相を管理できるようにし、処理を一時停止・再開し、オブジェクトコンテキストを定義し、およびタスクのデータにログに残せるようにします。ディスパッチオブジェクトは手動で保持され、解放されており、ガベージコレクションされません。




プログラムでディスパッチオブジェクトに関するデバッグ情報をログに記録します。


宣言

void dispatch_debug( dispatch_object_t object, const char *message, ...);


パラメーター

object内観すべきオブジェクト。
messageprintf スタイルの書式文字列の形式で、内観上でログに残すべきメッセージ。メッセージの内容は、"{dispatch_object_information}: メッセージ" のように、コロンで区切られたログメッセージに追加されます。

議論

デバッグ情報は、コンソールログに記録されます。この情報は、dispatch_debug 関数が呼び出された時にディスパッチオブジェクトの内部状態(現在の参照カウント、サスペンション数など) を表示するためのデバッグツールとして有用です。




オブジェクトのアプリケーションで定義されたコンテキストを返します。


宣言

void * dispatch_get_context( dispatch_object_t object);


パラメーター

objectこのパラメータは NULL にすることはできません。

戻り値

オブジェクトのコンテキスト。NULL にすることができます。


議論

あなたのアプリケーションはオブジェクトにカスタムコンテキストのデータを関連付けることができ、それはアプリケーションでのみ使用されます。あなたのアプリケーションは必要に応じてデータを割り当てたり、割り当てを解除する必要があります。




ディスパッチオブジェクトの参照(保持) カウントを減分します。


宣言

void dispatch_release( dispatch_object_t object);


パラメーター

obhect解放すべきオブジェクト。このパラメータは NULL にすることはできません。

議論

ディスパッチオブジェクトは非同期的に、それへのすべての参照が解放されると割り当て解除され(参照カウントがゼロになります)。あなたのアプリケーションは、もはやそれが作成したディスパッチオブジェクトを必要とせず、オブジェクトへのその関心を解放し、必要に応じてそのメモリの割り当てが解除できるようにするには、この関数を呼び出すべきです。GCD は、与えられたクライアントが与えられたオブジェクトへの最後または唯一の参照を持っていることを保証しないことに注意してください。



重要： アプリが展開ターゲットとして OS X v10.8 以降または iOS v6.0 以降でビルドされている場合は、ディスパッチキューは一般的に、ARC によって管理され、ディスパッチキューを保持または解放する必要はありません。

既存のコードとの互換性のため、この動作は構成可能です。詳しくは ディスパッチキューおよび自動リファレンスカウント を参照してください。


あなたのアプリケーションはグローバル(メイン main と同時 concurrent) ディスパッチキューを保持または解放する必要はありません。グローバルディスパッチキュー上で、この関数を呼び出しても効果はありません。



重要： 最後の参照が解放されたときにディスパッチオブジェクトが完全に再開できるるように dispatch_suspend と dispatch_resume への呼び出しのバランスを取ることが重要です。しばらく中断状態にあったディスパッチオブジェクトへの最後の参照を解放する動作は未定義です。




ディスパッチオブジェクト上でブロックオブジェクトの呼び出しを再開します。


宣言

void dispatch_resume( dispatch_object_t object);


パラメーター

object再開されるべきオブジェクト。このパラメータは NULL にすることはできません。

議論

この関数を呼び出すと、中断されたディスパッチキューやディスパッチイベントソースオブジェクトの中断カウントを、減分します。カウントがゼロよりも大きい間、オブジェクトは中断されたままです。中断カウントがゼロに戻ると、中断しているディスパッチキューで提出されたすべてのブロックまたはディスパッチソースで監視された全てのイベントが配信されます。


一つの例外を除いて、dispatch_resume への各呼び出しは dispatch_suspend への呼び出しとバランスを取る必要があります。dispatch_source_create によって返された新しいディスパッチイベントソースオブジェクトは、1 の中断カウントを持っていて、すべてのイベントが配信される前に再開されなければなりません。このアプローチは、アプリケーションが完全に最初のイベントの配信の前にディスパッチイベント・ソース・オブジェクトを構成できます。他のすべての場合、負の中断カウントになるだろう、dispatch_suspend より dispatch_resume の回数を呼び出すことは未定義です。




ディスパッチオブジェクトの参照(保持) カウントを増分します。


宣言

void dispatch_retain( dispatch_object_t object);


パラメーター

object保持すべきオブジェクト。このパラメータは NULL にすることはできません。

議論

この関数の呼び出しは dispatch_release の呼び出しでバランスをとらなければなりません。アプリケーションの複数のサブシステムがディスパッチオブジェクトを共有している場合、各サブシステムは、オブジェクト内に関心を登録するため dispatch_retain を呼び出す必要があります。オブジェクトは、すべてのサブシステムが、ディスパッチソースの関心を解放したときにのみ割り当てが解放されます。


アプリケーションはグローバル(メイン main と同時 concurrent) ディスパッチキューを保持または解放する必要がないことに注意してください。



重要： アプリが展開ターゲットを OS X v10.8 以降または iOS v6.0 以降でビルドされている場合は、一般的に、ARCによって管理されているので、ディスパッチキューを保持または解放する必要はありません。

既存のコードとの互換性のため、この動作は構成可能です。詳しくは ディスパッチキューおよび自動リファレンスカウント を参照してください。




オブジェクトとアプリケーションで定義されたコンテキストを関連付けます。


宣言

void dispatch_set_context( dispatch_object_t object, void *context);


パラメーター

objectこのパラメータは NULL にすることはできません。
contextオブジェクトの新しいアプリケーションで定義されたコンテキスト。これは、NULL にすることができます。

議論

あなたのアプリケーションはオブジェクトにカスタムコンテキストデータを関連付けることができ、アプリケーションでのみ使用されます。あなたのアプリケーションは必要に応じてデータの割り当てをし、割り当てを解除する必要があります。




ディスパッチオブジェクトにファイナライザ関数を設定します。


宣言

void dispatch_set_finalizer_f( dispatch_object_t object, dispatch_function_t finalizer);


パラメーター

object変更すべきディスパッチオブジェクト。このパラメータは NULL にすることはできません。
finalizerファイナライザ関数ポインタ。

議論

オブジェクトへのすべての参照が dispatch_release への呼び出しによって解放された後のディスパッチオブジェクト用のファイナライザは、そのオブジェクトのターゲット・キュー上に呼び出されます。アプリケーションは、オブジェクトのアプリケーションで定義されたコンテキストのように、オブジェクトに関連付けられたすべてのリソースを解放するために、ファイナライザを使用できます。ファイナライザ関数に渡されるコンテキストパラメータは、ファイナライザの呼び出しが行われた時点でのディスパッチオブジェクトの現在のコンテキストです。アプリケーションで定義されたコンテキストが NULL の場合、ファイナライザは呼び出されません。




ディスパッチオブジェクト上のブロックオブジェクトの呼び出しを停止します。


宣言

void dispatch_suspend( dispatch_object_t object);


パラメーター

object停止すべきディスパッチキューまたはディスパッチソース。(ディスパッチオブジェクトの他の種類を停止することはできません。) このパラメータは NULL にすることはできません。

議論

ディスパッチオブジェクトを停止することによって、あなたのアプリケーションは一時的にそのオブジェクトに関連付けられたすべてのブロックの実行を防ぐことができます。停止は、呼び出しの時に実行されているすべてのブロックが完了した後に発生します。この関数を呼び出すと、オブジェクトの停止カウントを増分し、dispatch_resume を呼び出すと、それを減分します。カウントがゼロよりも大きい間、オブジェクトは停止しており、各 dispatch_suspend の呼び出しを一致する dispatch_resume の呼び出しでバランスさせなければなりません。


一旦オブジェクトが再開されると、ディスパッチキューやディスパッチソースで監視されたイベントに提出されたブロックが配信されます。




手旗信号の使用


手旗信号ディスパッチは、伝統的な集計手旗信号の効率的な実装です。呼び出し元のスレッドがブロックされる必要がある場合にのみ手旗信号ディスパッチはカーネルを下がって呼び出します。呼び出した手旗信号はブロックする必要がない場合、カーネルの呼び出しは行われません。




初期値を持つ新しい集計手旗信号を作成します。


宣言

dispatch_semaphore_t dispatch_semaphore_create( long value);


パラメーター

value手旗信号の開始値。ゼロ未満の値を渡すと、NULL が返されます。

戻り値

新たに作成した手旗信号、または失敗した場合には NULL。


議論

値にゼロを渡すと、二つのスレッドが特定のイベントの完了を調整する必要がある場合に便利です。ゼロより大きな値を渡すと、リソースの有限プールを管理するのに便利で、プールサイズは値に等しいです。


アプリケーションがもはや手旗信号を必要としないとき、それは、手旗信号オブジェクトへの参照を解放し、そのメモリを最終的に自由にするため dispatch_release を呼び出すべきです。




手旗信号への信号(増分)


宣言

long dispatch_semaphore_signal( dispatch_semaphore_t dsema);


パラメーター

dsema集計手旗信号。このパラメータは NULL にすることはできません。

戻り値

この関数は、スレッドが起こされた場合、ゼロ以外の値を返します。それ以外の場合は、ゼロが返されます。


議論

集計手旗信号を増分します。前の値がゼロ未満であった場合、この関数は、現在 dispatch_semaphore_wait で待機しているスレッドを起動します。




手旗信号の待機(減分)。


宣言

long dispatch_semaphore_wait( dispatch_semaphore_t dsema, dispatch_time_t timeout);


パラメーター

dsema手旗信号。このパラメータは NULL にすることはできません。
timeoutタイムアウトする時(dispatch_time を参照の事)。定数 DISPATCH_TIME_NOW と DISPATCH_TIME_FOREVER は、利便性のため利用できます。

戻り値

成功した場合はゼロ、またはタイムアウトが発生した場合、ゼロ以外の値を返します。


議論

集計手旗信号を減分します。結果の値がゼロ未満である場合、この関数は返す前に、信号が発生するのを FIFO 順で待機します。




バリアの使用


ディスパッチバリアを使用すると、同時ディスパッチキュー内の同期ポイントを作成できます。それがバリアに遭遇すると、すべてのブロックがバリアの実行を終了する前に提出するまでバリアブロックの実行(または全ての更なるブロック) の実行を遅延させます。この時点で、バリアブロックはそれ自体で実行されます。完了すると、キューは通常の実行動作を再開します。




非同期実行用のバリアブロックを提出し、すぐに返ります。


宣言

void dispatch_barrier_async( dispatch_queue_t queue, dispatch_block_t block);


パラメーター

queueその上でバリアブロックを実行すべきディスパッチキュー。ブロックが実行を完了するまでキューはシステムによって保持されます。このパラメータは NULL にすることはできません。
blockターゲット・ディスパッチキューに提出すべきバリアブロック。実行が終了し、その時にそれが解放されるまでこのブロックはコピーされ、保持されます。このパラメータは NULL にすることはできません。

議論

この関数への呼び出しは常にブロックが提出された直後に返り、ブロックが呼び出されるのを待つことはありません。バリアブロックがプライベートの同時キューの先頭に到達しても、それは即座に実行されません。代わりに、現在実行中のブロックが実行を終了するまで、キューは待機します。その時点で、バリアブロックはそれ自身で実行されます。バリアブロックの後に提出されたブロックはバリアブロックが完了するまで実行されません。


指定したキューは、あなた自身が dispatch_queue_create 関数を使って作成する同時キューでなければなりません。この関数に渡すキューがシリアルキューまたはグローバルの同時キューの一つである場合、この関数は dispatch_async 関数のように動作します。




非同期実行用のバリア関数を提出し、すぐに返ります。


宣言

void dispatch_barrier_async_f( dispatch_queue_t queue, void* context, dispatch_function_t work);


パラメーター

queueその上でバリア関数を実行すべきディスパッチキュー。関数が実行を完了するまでキューはシステムによって保持されます。このパラメータは NULL にすることはできません。
context関数に渡すべきアプリケーションで定義されたコンテキストパラメータ。
work実行するべきアプリケーションで定義されたバリア関数。この関数に渡される最初のパラメータは、context パラメータの値です。このパラメータは NULL にすることはできません。

議論

この関数への呼び出しは常にバリア関数が提出された直後に返り、その関数が呼び出されるのを待つことは決してありません。バリア関数がプライベートの同時キューの先頭に到達しても、それは即座に実行されません。代わりに、現在実行中のブロックが実行が終了するまで、キューが待機します。その時点でキューは、それ自身、バリア関数を実行します。バリア関数が完了するまで、バリア関数の後に提出されたブロックは実行されません。


指定したキューは、あなた自身が dispatch_queue_create 関数を使って作成した同時キューでなければなりません。この関数に渡すキューがシリアルキューまたはグローバルの同時キューの一つである場合、この関数は dispatch_async 関数のように動作します。




実行のためにバリアブロックオブジェクトを提出し、そのブロックが完了するまで待機します。


void dispatch_barrier_sync( dispatch_queue_t queue, dispatch_block_t block);


パラメーター

queueその上でバリアブロックを実行するべきディスパッチキュー。このパラメータは NULL にすることはできません。
block実行されるべきバリアブロック。このパラメータは NULL にすることはできません。

議論

同期実行のためディスパッチキューにバリアブロックを提出します。dispatch_barrier_async とは異なり、バリアブロックが終了するまでこの関数は戻りません。この関数を呼び出して、現在のキューをターゲットにするとそのの結果はデッドロックに陥ります。


バリアブロックがプライベートの同時キューの先頭に到達しても、それは即座に実行されません。代わりに、その現在実行中のブロックが実行が終了するまで、キューは待機します。その時点で、キューはそれ自身で、バリアブロックを実行します。バリアブロックが完了するまでバリアブロックの後に提出されたブロックは実行されません。


指定したキューは、あなたが dispatch_queue_create 関数を使って自分で作成する同時キューでなければなりません。この関数に渡すキューがシリアルキューまたはグローバルの同時キューの一つである場合、この関数は dispatch_sync 関数のように動作します。


dispatch_barrier_async とは異なり、ターゲット・キュー上では retain(保持) は実行されません。この関数への呼び出しは非同期のため、これは呼び出し元の参照を"借用" (borrow) します。しかも、Block_copy はブロック上で実行されません。


最適化のため、この関数は、可能な場合、現在のスレッド上にバリアブロックを呼び出します。




実行のためにバリア関数を提出し、その関数が完了するまで待機します。


宣言

void dispatch_barrier_sync_f( dispatch_queue_t queue, void* context, dispatch_function_t work);


パラメーター

queueその上でバリア関数を実行すべきディスパッチキュー。このパラメータは NULL にすることはできません。
contextバリア関数に渡すべきアプリケーションで定義されたコンテキストパラメータ。
work実行すべきアプリケーションで定義されたバリア関数。この関数に渡される最初のパラメータは、context パラメータの値です。このパラメータは NULL にすることはできません。

議論

同期実行のためディスパッチキューにバリア関数を提出します。dispatch_barrier_async_f とは異なり、バリア関数が終了するまでこの関数は戻りません。この関数を呼び出し、現在のキューをターゲットにすると、デッドロックに陥ります。


バリア関数がプライベートの同時キューの先頭に到達しても、それは即座に実行されません。代わりに、その現在実行中のブロックの実行が終了するまで、キューは待機します。その時点で、キューはそれ自身で、バリア関数を実行します。バリア関数が完了するまで、バリア関数の後に提出されたブロックは実行されません。


指定したキューは、あなた自身が dispatch_queue_create 関数を使って作成する同時キューでなければなりません。この関数に渡すキューはシリアルキューまたはグローバルの同時キューの一つである場合、この関数は dispatch_sync_f 関数のように動作します。


dispatch_barrier_async_f とは異なり、ターゲット・キュー上で retain (保持) は実行されません。この関数の呼び出しは同期のため、呼び出し元の参照を"借用"(borrow) します。


最適化のため、この関数は可能な場合、現在のスレッド上のバリア関数を呼び出します。




ディスパッチソースの管理


GCD は、アクティビティー(UNIX の記述子、Mach のポート、Unix の信号、VFS　ノードなどのような低レベルのシステムオブジェクト) を監視するためのインターフェース、すなわちディスパッチソースの一組を提供しています。このようなアクティビティーが発生した時、ディスパッチキューにイベントハンドラを提出します。イベントが発生すると、ディスパッチソースは、処理のために指定されたディスパッチキューに非同期のタスクコードを提出します。




非同期的にディスパッチソースをキャンセルし、そのイベントハンドラブロックのさらなる呼び出しを防止します。


宣言

void dispatch_source_cancel( dispatch_source_t source);


パラメーター

sourceキャンセルすべきディスパッチソース。このパラメータは NULL にすることはできません。

議論

キャンセルは、指定されたディスパッチソースのイベントハンドラブロックの全てのさらなる呼び出しを防ぎますが、すでに進行中のイベントハンドラブロックは中断されません。イベントハンドラブロックが完了した後、オプションのキャンセルハンドラは、ターゲット・キューに提出されます。


ソースのイベントハンドラが終了した場合キャンセルハンドラは、ソースのターゲットに提出され、ソースのハンドル(ファイル記述子や mach ポート) を閉じても安全であることを示します。


オプションのキャンセルハンドラは、システムが、全ての基礎となるシステム・オブジェクト(ファイル記述子や mach ポート) への参照をすべて解放した後にのみディスパッチソースオブジェクトのターゲット・キューに提出されます。したがって、キャンセルハンドラは、そのようなシステムオブジェクトを閉じたり、割り当てを解除するのに便利な所です。キャンセルハンドラが呼び出される前に、ディスパッチソースオブジェクトによって現在追跡されている mach ポートをファイル記述子を閉じたり、割り当て解除するのは無効であることに注意してください。


以下も見よ

dispatch_source_set_cancel_handler




低レベルのシステムオブジェクトをモニターし、自動的にイベントに応答してディスパッチキューにハンドラブロックを提出するための新しいディスパッチソースを作成します。


宣言

dispatch_source_t dispatch_source_create( dispatch_source_type_t type, uintptr_t handle, unsigned long mask, dispatch_queue_t queue);


パラメーター

typeディスパッチソースの型。ディスパッチ・ソース型の定数 にリストされている定数のいずれかでなければなりません。
handleモニターするべき基礎となるシステム・ハンドル。この引数の解釈は型パラメータに指定された定数によって決定されます。
maskイベントが望まれている指定されたフラグのマスク。この引数の解釈は型パラメータに指定された定数によって決定されます。
queueイベントハンドラブロックが提出されるべきディスパッチキュー。

戻り値

新しいディスパッチソースオブジェクトまたはディスパッチソースが作成できなかった場合 NULL。


議論

ディスパッチソースはリエントラント(複数のプログラムが同時に共有するもの) ではありません。全てのイベントはディスパッチソースが中断されているか、イベントハンドラブロックが現在合体して配信されており、ディスパッチソースが再開されるか、イベントハンドラブロックが戻ってきた後、受信します。


ディスパッチソースは中断状態で作成されます。全ての望みの属性を設定し、ソースを作成した後(例えば、ハンドラまたはコンテキスト)、アプリケーションは、イベント・デリバリーを開始するため dispatch_resume を呼び出す必要があります。


あなたのアプリケーションが、もはやイベントソースを必要としない場合は、ソースオブジェクトへの参照を解放し、そのメモリ最終的に自由にするため dispatch_release を呼び出すべきです。




ディスパッチソースの保留中のデータを返します。


宣言

unsigned long dispatch_source_get_data( dispatch_source_t source);


パラメーター

sourceこのパラメーターは NULL にすることはできません。

戻り値は、ディスパッチソースの型に応じて解釈され、次のうちの一つになります。


議論

イベントハンドラブロック内からこの関数を呼び出します。イベントハンドラのコールバックの外でこの関数を呼び出した結果は未定義です。




指定されたディスパッチソースに関連する、基礎となるシステムのハンドルを返します。


宣言

uintptr_t dispatch_source_get_handle( dispatch_source_t source);


パラメーター

sourceこのパラメーターは NULL にすることはできません。

戻り値

戻り値は、ディスパッチソースの型に応じて解釈され、次のハンドルのうちの一つになります。


議論

返されたハンドルは、基礎となるシステムオブジェクトへの参照であり、ディスパッチソースによってモニターされています。




ディスパッチソースによってモニターされたイベントのマスクを返します。


宣言

unsigned long dispatch_source_get_mask( dispatch_source_t source);


パラメーター

sourceこのパラメーターは NULL にすることはできません。

戻り値

戻り値は、ディスパッチソースの型に応じて解釈されるべきであり、以下のフラグのセットの一つになります。


議論

マスクは、関連イベントのビットマスクであり、ディスパッチイベントソースによってモニターされています。イベントマスクで指定されていない全てのイベントは無視され、イベントハンドラブロックは、それらのために全く提出されません。


詳細については、定数 のフラグの説明を参照してください。




DISPATCH_SOURCE_T YPE_DATA_ADD または DISPATCH_SOURCE_TYPE_DATA_OR 型のディスパッチソースにデータをマージし、そのターゲット・キューにそのイベントハンドラブロックを提出します。


宣言

void dispatch_source_merge_data( dispatch_source_t source, unsigned long value);


パラメーター

sourceこのパラメーターは NULL にすることはできません。
value保留中のデータがディスパッチソースタイプで指定された論理 OR または ADD を使用して合体した値。ゼロの値は効果がなく、イベントハンドラブロックの提出をもたらしません。

議論

あなたのアプリケーションは、イベントが DISPATCH_SOURCE_TYPE_DATA_ADD または DISPATCH_SOURCE_TYPE_DATA_OR 型のアプリケーションで定義されたディスパッチイベント・ソースの一つで発生したことを示すために、この関数を使用できます。




与えられたディスパッチソース用の登録ハンドラブロックを設定します。


宣言

void dispatch_source_set_registration_handler( dispatch_source_t source, dispatch_block_t registration_handler);


パラメーター

source変更すべきディスパッチソース。このパラメータは NULL にすることはできません。
registration_handlerインストールすべき登録ハンドラブロック。新しいものをインストールする前に以前の登録ハンドラは(もしあれば) 解放されます。この関数は、新規登録ハンドラのコピーを格納するために Block_copy の呼び出しを使用します。このパラメータは NULL にすることができます。

議論

登録ハンドラ(指定されている場合) はソースが完全に設定され、イベントの配信を開始する準備ができるや否や、ソースのターゲット・キューに提出されます。ディスパッチソースの基礎となるイベント・デリバリーメカニズムの設定は非同期に起こります。登録ハンドラをインストールするのは、その設定は完了し、ディスパッチソースがイベントの配信を開始する準備ができたときに通知される方法です。


あなたの操作ハンドラが実行された後、ディスパッチソースはそれをアンインストールします。このように、登録ハンドラは一度だけあなたがディスパッチソースを再開した後に実行されます。


すでに設定され、実行されているディスパッチソースの登録ハンドラをインストールする場合は、あなたのハンドラはすぐに呼び出されます。




与えられたディスパッチソースの登録ハンドラ関数を設定します。


宣言

void dispatch_source_set_registration_handler_f( dispatch_source_t source, dispatch_function_t registration_handler);


パラメーター

source変更すべきディスパッチソース。このパラメータは NULL にすることはできません。
registration_handlerインストールすべき登録ハンドラ関数。新しいものをインストールする前に以前の登録ハンドラは、(もしあれば) 解放されます。イベントハンドラ関数に渡されたコンテキストパラメータは、ハンドラの呼び出しが行われた時点でのディスパッチソースの現在のコンテキストです。このパラメータは NULL にすることができます。

議論

登録ハンドラ(指定されている場合) はすぐにソースが完全に設定され、イベントの配信を開始する準備ができるやいなや、ソースのターゲット・キューに提出されます。ディスパッチソースの基礎となるイベント・デリバリーメカニズムの設定は非同期的に起こります。登録ハンドラをインストールすると、その設定が完了し、ディスパッチソースがイベントの配信を開始する準備ができたときに通知される方法です。


あなたの操作ハンドラが実行された後、ディスパッチソースはそれをアンインストールします。このように、登録ハンドラは一度だけあなたがディスパッチソースを再開した後に実行されます。


すでに設定され、実行されているディスパッチソースの登録ハンドラをインストールする場合、あなたのハンドラはすぐに呼び出されます。




与えられたディスパッチソースのキャンセルハンドラブロックを設定します。


void dispatch_source_set_cancel_handler( dispatch_source_t source, dispatch_block_t cancel_handler);


パラメーター

source変更すべきディスパッチソース。このパラメータは NULL にすることはできません。
handlerソースのターゲット・キューに提出すべきキャンセルハンドラブロック。この関数は、呼び出し元に代わって Block_copy を実行し、以前のハンドラ(もしあれば) にBlock_release を実行します。このパラメータは NULL にすることができます。

議論

キャンセルハンドラ(指定されている場合) は、システムが、ソースの基になるハンドルとソースのイベントハンドラブロックが返したすべての参照を解放した時、dispatch_source_cancel への呼び出しに応答して、ソースのターゲットキューに提出されます。



重要： 安全にファイル記述子を閉じたり、Mach ポートを破壊するには、キャンセルハンドラがその記述子またはポートのソースのため必須です。キャンセルハンドラを実行する前に記述子またはポートを閉じると、競合状態になることがあります。新しい記述子がソースのイベントハンドラがまだ実行されている間に最近閉じられた記述子と同じ値が割り当てられている場合は、イベント・ハンドラは、間違った記述子を使用して、データの読み書きをすることがあります。




与えられたディスパッチソースのキャンセルハンドラ関数を設定します。


宣言

void dispatch_source_set_cancel_handler_f( dispatch_source_t source, dispatch_function_t cancel_handler);


パラメーター

source変更すべきディスパッチソース。このパラメータは NULL にすることはできません。
handlerソースのターゲット・キューに提出されるべきキャンセルハンドラ関数。イベントハンドラ関数に渡されたコンテキストパラメータは、ハンドラの呼び出しが行われた時点でのディスパッチソースの現在のコンテキストです。

議論

キャンセルハンドラ(指定されている場合) は、システムが、ソースの基になるハンドルとソースのイベントハンドラブロックが返したすべての参照を解放した時、dispatch_source_cancel への呼び出しに応答して、ソースのターゲットキューに提出されます。



重要： 安全にファイル記述子を閉じたり、Mach ポートを破壊するには、キャンセルハンドラがその記述子またはポートのソースのため必須です。キャンセルハンドラを実行する前に記述子またはポートを閉じると、競合状態になることがあります。新しい記述子がソースのイベントハンドラがまだ実行されている間に最近閉じられた記述子と同じ値が割り当てられている場合は、イベント・ハンドラは、間違った記述子を使用して、データの読み書きをすることがあります。




与えられたディスパッチソースのイベントハンドラブロックを設定します。


宣言

void dispatch_source_set_event_handler( dispatch_source_t source, dispatch_block_t handler);


パラメーター

source変更すべきディスパッチソース。このパラメータは NULL にすることはできません。
handlerソースのターゲット・キューに提出すべきイベントハンドラブロック。この関数は、呼び出し元に代わって Block_copy を実行し、以前のハンドラ(もしあれば) で Block_release を実行します。このパラメータは NULL にすることはできません。

議論

イベントハンドラ(指定した場合) は、イベントの到着に応答して、ソースのターゲットキューに提出されます。




与えられたディスパッチソースのイベントハンドラ関数を設定します。


宣言

void dispatch_source_set_event_handler_f( dispatch_source_t source, dispatch_function_t handler);


パラメーター

source変更すべきディスパッチソース。このパラメータは NULL にすることはできません。
handlerソースのターゲット・キューに提出すべきイベントハンドラブロック。イベントハンドラ関数に渡されたコンテキストパラメータは、ハンドラの呼び出しが行われた時点でのディスパッチソースの現在のコンテキストです。このパラメータは NULL にすることはできません。

議論

イベントハンドラ(指定した場合) は、イベントの到着に応答して、ソースのターゲットキューに提出されます。




タイマーソースの開始時刻、間隔、および余裕値を設定します。


宣言

void dispatch_source_set_timer( dispatch_source_t source, dispatch_time_t start, uint64_t interval, uint64_t leeway);


パラメーター

startタイマーの開始時刻。詳細については、dispatch_time と dispatch_walltime を参照してください。
intervalタイマーのナノセカンド単位の間隔。
leewayシステムがタイマーを延期できる、ナノセカンド単位での、時間の量。

議論

あなたのアプリケーションは、必要に応じてタイマーソースの時間間隔をリセットするため、同じディスパッチタイマーソースオブジェクトにこの関数を複数回呼び出すことができます。


start 時刻のパラメータも、タイマーのために使用されるクロックを決定します。開始時刻が DISPATCH_TIME_NOW か、または dispatch_time で作成された場合、タイマーは mach_absolute_time に基づいています。それ以外の場合、タイマーの開始時間が dispatch_walltime で作成された場合、タイマーは gettimeofday(3) に基づいています。


leeway パラメータは、ナノセカンド単位で、時間の量とこれに改良されたシステムの性能や消費電力の他のシステムのアクティビティと整合するタイマーを延期することができる、アプリケーションからのヒントです。たとえば、アプリケーションは最大 30 秒の余裕(leeway) と、定期的なタスクを 5 分ごとに実行できます。余裕値がゼロに指定されている場合でも、すべてのタイマーに少しの待ち時間が予想されることに注意してください。


タイマーソースが既にキャンセルされた場合、この関数を呼び出しても効果はありません。




与えられたディスパッチソースがキャンセルされたかどうかをテストします。


宣言

long dispatch_source_testcancel( dispatch_source_t source);


パラメーター

sourceテストされるべきディスパッチソース。このパラメータは NULL にすることはできません。

戻り値

キャンセルされた場合ゼロ以外の値、キャンセルされない場合ゼロ。


議論

あなたのアプリケーションは、ディスパッチソースオブジェクトが dispatch_source_cancel への呼び出しによってキャンセルされたかどうかをテストするには、この機能を使用できます。この関数の結果は dispatch_source_cancel が呼び出された直後にゼロでなくなります。




ディスパッチ I/O コンビニエンス API を使用して


ディスパッチ I/O のコンビニエンス API を使用すると、ファイル記述子の非同期読み込みと書き込み操作を実行できます。この API は、ファイル記述子のコンテンツにアクセスするためのストリームに基礎を置いた意味をサポートします。




指定されたファイル記述子を使用して非同期読み出し操作をスケジュールします。


宣言

void dispatch_read( dispatch_fd_t fd, size_t length, dispatch_queue_t queue, void (^handler)(dispatch_data_t data, int error));


パラメーター

fdそこからデータを読み出すべきファイルディスクリプタ。
lengthファイルディスクリプタから読み込むべき最大データ量。
queueその上で指定されたハンドラブロックを実行すべきキュー。
handler指定された量のデータが読み込まれたか、エラーが発生したときに実行をスケジュールするべきブロック。ハンドラのパラメータは以下のとおりです。
    data - ファイル記述子から読み取られたデータ。現在のファイル記述子から利用可能なだけのデータを、指定された長さまで、このオブジェクトは含んでいます。このオブジェクトはシステムによって所有され、ハンドラが返ったときに解放されます。あなたがデータを引き続き使用したい場合は、あなたのハンドラは、このオブジェクトを保持するか、戻る前に別の場所にデータをコピーする必要があります。
    error - データが正常に読み込まれたか、EOF に達した場合、この値は 0 です。エラーが発生した場合、このパラメータはエラー番号を含んでいます。

議論

これは、指定されたファイル記述子の現在の位置から単一の、非同期の読み出し操作を開始するためのコンビニエンス関数です。このメソッドは、あなたがチャンネルを作成するオーバーヘッドを必要とせず、データを読み書きするために、多くの呼び出しを発行する必要がない簡単な操作のために意図されています。一旦提出されると、読み出し動作をキャンセルする方法はありません。


ハンドラブロックがキューに登録されるまで、この関数を呼び出した後、システムは指定されたファイル記述子を制御します。ファイル記述子を制御しながら、システムは、アプリケーションに代わって、それを変更できます。例えばシステムは、典型的には、すべての操作はブロックしないことを確実にするために O_NONBLOCK フラグを付加します。その間直接、ファイル記述子を変更するのは、アプリケーションのエラーです。しかし、この関数または追加の読み書きを実行するための dispatch_write 関数にファイル記述子を渡すことができます。また、新しいディスパッチ I/O チャンネルを作成するために、ファイル記述子を使用してもよいです。


読み取り操作が終了するまで、あなたが提供するハンドラは、実行のためにキューにされていません。コンビニエンス API を使用して同じファイル記述子のための複数の読み書きの呼び出しを発行した場合、関連するハンドラのいずれかがキューにされる前に、それらの操作のすべてが完了しなければなりません。すでに別のチャンネルでファイル記述子を使用している場合、この関数を使用するよりも、チャンネルからデータを読み取る、dispatch_io_read 関数を使用する必要があります。


ファイルの終わりを超えて読み取ろうとすると、あなたのハンドラは空のデータオブジェクトとエラーコード 0 を渡されます。回復不可能なエラーの他の型の場合、適切なエラーコードは、エラーが発生する前に読まれたどのようなデータでも一緒に返されます。




指定されたファイル記述子を使用して非同期の書き込み操作をスケジュールします。


宣言

void dispatch_write( dispatch_fd_t fd, dispatch_data_t data, dispatch_queue_t queue, void (^handler)(dispatch_data_t data, int error));


パラメーター

fdデータの書き込み時に使用するファイル記述子。
dataファイル記述子に書き込むべきデータ。
queueその上で指定されたハンドラブロックを実行すべきキュー。
handler指定されたデータが、ファイル記述子に書き込まれた後、実行のためスケジュールされたブロック。ハンドラのパラメータは以下のとおりです。
    data - ファイル記述子に書き込めなかったデータ。データが正常に書き込まれた場合、このパラメータは NULL です。
    error - データが正常に書き込まれた場合、この値は 0 です。エラーが発生した場合、このパラメータはエラー番号を含んでいます。

議論

これは、指定されたファイル記述子の現在の位置に単一の、非同期の書き込み操作を開始するためのコンビニエンス関数です。このメソッドは、あなたがチャンネルを作成するオーバーヘッドを必要とせず、データを読み書きするために、多くの呼び出しを発行する必要がない簡単な操作のために意図されています。一旦提出されると、書き込み操作をキャンセルする方法はありません。


ハンドラブロックがキューに登録されるまで、この関数を呼び出した後、システムは指定されたファイル記述子を制御します。ファイル記述子を制御しながら、システムは、アプリケーションに代わって、それを変更できます。例えば、システムは、典型的には、すべての操作はブロックしないことを確実にするために O_NONBLOCK フラグを付加します。その間直接、ファイル記述子を変更するのは、アプリケーションのエラーです。しかし、この関数または dispatch_read 関数にファイル記述子を渡すことができます。また、新しいディスパッチ I/O チャンネルを作成するために、ファイル記述子を使用してもよいです。システムはあなたのハンドラを呼び出す前に、ファイル記述子の制御を放棄するので、あなたのハンドラコードから再度ファイル記述子を変更しても安全です。


書き込み操作が終了するまで、あなたが提供する handler は、実行のためにキューにされていません。さらに、コンビニエンス API を使用して同じファイル記述子の複数の読み書きの呼び出しを発行した場合、関連するハンドラのいずれかがキューにされる前に、また、それらの操作のすべてが完了しなければなりません。すでに別のチャンネルでファイル記述子を使用している場合は、この関数を使用するよりはチャンネルにデータを書き込む、dispatch_io_write 関数を使用する必要があります。




ディスパッチ I/O チャンネル API を使用して


ディスパッチ I/O チャンネル API を使用すると、ファイル記述子をベースにした操作を管理できます。この API は、ファイル記述子のコンテンツにアクセスするためのストリームを基礎にしたものとランダムアクセスの意味をサポートしています。




ディスパッチ I/O チャンネルを作成し、指定されたファイル記述子にそれを関連付けます。


宣言

dispatch_io_t dispatch_io_create( dispatch_io_type_t type, dispatch_fd_t fd, dispatch_queue_t queue, void (^cleanup_handler)(int error));


パラメーター

type作成すべきチャンネルの型。可能なオプションのリストについては、ディスパッチ I/O チャンネルの型 を参照してください。
fdチャンネルに関連付けるべきファイル記述子。
queueチャンネルに関連付けるべきディスパッチキュー。このキューは、チャンネルのクリーンアップハンドラを実行するために使用されます。チャンネルは、このキューを保持します。
cleanup_handlerシステムが、チャンネルのファイル記述子の制御を放棄する時、キューにすべきブロック。このチャンネルは、制御が放棄された理由を示す単一のパラメーターを取ります。error パラメータがゼロ以外の値が含んでいる場合は、チャンネルの作成中にエラーがあったため、制御が放棄されました。それ以外の場合、この値は 0 になります。

戻り値

ディスパッチ I/O チャンネルまたはエラーが発生した場合 NULL。返される前、返されたオブジェクトは保持されます。それを使用して行われた時、あなたにはチャンネルを閉じてこのオブジェクトを解放する責任があります。


議論

既に開いているファイル記述子のディスパッチ I/O チャンネルを作成するには、この関数を使用してください。この関数を呼び出した後、システムは、以下の 1 つが発生するまで、指定されたファイル記述子の制御を行います。


ファイル記述子を制御しながら、システムは、アプリケーションに代わって、そのファイル記述子を変更できます。例えば、システムは通常、ファイル記述子上の全ての操作がブロックしていないことを保証するために O_NONBLOCK フラグを追加します。その間、ファイル記述子を直接変更するのは、アプリケーションのエラーです。しかし、同じファイル記述子を使用して追加のチャンネルを作成できます。




関連するパス名を持つディスパッチ I/O チャンネルを作成します。


宣言

dispatch_io_t dispatch_io_create_with_path( dispatch_io_type_t type, const char* path, int oflag, mode_t mode, dispatch_queue_t queue, void (^cleanup_handler)(int error));


パラメーター

type作成すべきチャンネルの型。可能なオプションのリストについては、ディスパッチ I/O チャンネルの型 を参照してください。
path開いて、チャんネル I/O に使用すべきファイルシステムパス。このパスは、open システムコールを使用して開かれます。
oflagパスを開くときに open 関数に渡すべきフラグ。
mode指定したパスのファイルを作成するときに、open 関数に渡すべきモード。ファイルを作成していない場合は、0 を指定します。
queueチャンネルに関連付けるべきディスパッチキュー。このキューは、チャンネルのクリーンアップハンドラを実行するために使用されます。チャンネルは、このキューを保持します。
cleanup_handlerシステムが、チャンネルのファイル記述子の制御を放棄するときにキューにするブロック。このチャンネルは、制御が放棄された理由を示す単一のパラメータを取ります。error パラメータがゼロでない値を含んでいる場合は、チャンネルの作成中にエラーがあったため、制御が放棄されました。それ以外の場合、この値は 0 であるべきです。

戻り値

ディスパッチ I/O チャンネルまたはエラーが発生した場合 NULL。それが返される前返されたオブジェクトは保持されます。それを使用して行われるときに、チャンネルを閉じて、このオブジェクトを解放する責任はあなたにあります。


議論

この関数は、指定されたパスをチャンネルに関連付けますが、最初に I/O 操作を実行するまで、そのパスのファイル記述子を開きません。それが開いている間、チャンネルはファイル記述子を所有しています。チャンネルは、ファイル記述子を閉じ、以下のいずれか一つが発生した時、そのクリーンアップハンドラを呼び出します。





既存のチャンネルから新しいディスパッチ I/O チャンネルを作成します。


宣言

dispatch_io_t dispatch_io_create_with_io( dispatch_io_type_t type, dispatch_io_t io, dispatch_queue_t queue, void (^cleanup_handler)(int error));


パラメーター

type作成するべきチャンネルの型。可能なオプションのリストについては、ディスパッチ I/O チャンネルの型 を参照してください。
io使用したいファイル記述子またはパス名の既存のチャンネル。
queueチャンネルに関連付けるべきディスパッチキュー。このキューは、チャンネルのクリーンアップハンドラを実行するために使用されます。チャンネルは、このキューを保持します。
cleanup_handlerシステムがチャンネルのファイル記述子の制御を放棄する時、キューにするブロック。このチャンネルは、制御が放棄された理由を示す単一のパラメータを取ります。error パラメーターがゼロでない値を含んでいる場合は、チャンネルの作成中にエラーがあったため、制御が放棄されました。それ以外の場合、この値は 0 であるべきです。

戻り値

ディスパッチ I/O チャンネルまたはエラーが発生した場合 NULL。それが返される前返されたオブジェクトは保持されます。それを使用して行われるときに、チャンネルを閉じて、このオブジェクトを解放する責任はあなたにあります。


議論

この関数は、ファイル記述子または指定したチャンネルのパス名を継承する新しいディスパッチ I/O チャンネルを作成しますが、そのチャンネルの型とポリシーはあなたが異なるように設定できます。


既存のチャンネルがファイル記述子に関連付けられている場合、システムは新しいチャンネルも閉じられるまでファイル記述子上で制御を維持し、エラーはファイル記述子上で発生し、またはそのファイル記述子に結びついたチャンネルへへのすべての参照が解放されます。ファイル記述子が解放されると、cleanup_handler ブロックは、指定されたqueue 上でキューにされ、システムはファイル記述子の制御を放棄します。


それが、ファイル記述子を制御している時、システムは、アプリケーションに代わって、そのファイル記述子を修正できます。例えば、システムは通常、ファイル記述子上の全ての操作が非ブロックしていない事を保証するために O_NONBLOCK フラグを追加します。その間直接、ファイル記述子を変更するのは、アプリケーションのエラーです。しかし、同じファイル記述子を使用して追加のチャンネルを作成できます。




非同期的に指定したチャンネルの読み込み操作をスケジュールします。


宣言

void dispatch_io_read( dispatch_io_t channel, off_t offset, size_t length, dispatch_queue_t queue, dispatch_io_handler_t io_handler);


パラメーター

channelデータ読み出し時使用すべきチャンネル。
offswetランダムアクセスチャンネルの場合、このパラメーターは読み込み元のチャンネルへのオフセットを指定します。オフセットは、チャンネルが作成された時点でのチャンネルのファイル記述子の相対初期ファイルポインタを指定されたものです。

ストリームベースのチャンネルの場合、このパラメーターは無視され、データは現在の位置から読み込まれます。
lengthチャンネルから読み取るべきバイト数。EOF に到達するまでデータを読み続けるには SIZE_MAXZ を指定します。
queueその上で io_handler ブロックを提出すべきディスパッチキュー。
io_handlerチャンネルからデータを読み出すプロセスに使用するブロック。このブロックは、与えられたデータ要求を処理するために複数回キューに入れられます。ブロックがキューに入れられるたびに、ハンドラに渡される data パラメーターは、データの最も最近読んだ塊を含んでいます。

あなたのブロックがリエントラント(複数のプログラムがタスクを共有するのが可能) である必要はありません。システムは、このブロックのインスタンスが 1 つだけ任意の与えられた時間に実行されることを保証します。

議論

この関数は、指定されたデータを読み取り、データを処理するために queue に io_handler ブロックを提出します。ハンドラの done パラメータが NO に設定されている場合、データの一部のみが読み取られたことを意味します。done パラメーターが YES に設定されている場合は、読み出し動作が完了していて、ハンドラが再度提出されないことを意味します。回復不能なエラーがチャンネルのファイル記述子で発生した場合、done パラメーターが YES に設定され、適切なエラー値が、ハンドラの error パラメータで報告されます。


done パラメーターが YES にセットされてハンドルが done パラメータセットに提出された場合、空のデータオブジェクト、および 0 のエラーコードになり、そのチャンネルは、ファイルの終わりに達したことを意味します。




指定したチャンネルの非同期書き込み操作をスケジュールします。


void dispatch_io_write( dispatch_io_t channel, off_t offset, dispatch_data_t data, dispatch_queue_t queue, dispatch_io_handler_t io_handler);


パラメーター

channelデータを書き込む時使用するチャンネル。
offsetランダムアクセスチャンネルの場合、このパラメータは書き込むチャンネルへのオフセットを指定します。オフセットは、チャンネルが作成された時点でのチャンネルのファイル記述子の相対初期ファイルポインタを指定されたものです。

ストリームベースのチャンネルの場合、このパラメーターは無視され、データは現在の位置に書き込まれます。
dataチャンネルに書き込むべきデータ。
queueその上に io_handler ブロックを提出すべきディスパッチキュー。
io_handler任意の進捗状況を報告するために使用するべきブロック。このブロックは、与えられたデータ要求を処理するために複数回キューに入れられます。ブロックがキューに入れられるたびに、ハンドラに渡される data パラメータは書き込まれるのが残っているデータを含んでいます。

あなたのブロックはリエントラント(複数のプログラムがタスクを共有するのが可能) である必要はありません。システムは、このブロックのインスタンスが 1 つだけ任意の与えられた時間に実行されることを保証します。

議論

この関数は、指定されたデータを書き込み、操作の進捗状況を報告するために queue に io_handler ブロックを提出します。ハンドラの done パラメータが NO に設定されている場合、データの一部のみが書き込まれたことを意味します。done パラメーターが YES に設定されている場合、書き込み操作が完了していて、ハンドラは再度提出されないことを意味します。操作が成功した場合、ハンドラの error パラメーターは、0 に設定されます。しかし、回復不能なエラーがチャンネルのファイル記述子に発生した場合、done パラメーターは YES に設定され、適切なエラー値が、ハンドラの error パラメータで報告されています。




新しい読み書き操作に指定されたチャンネルを閉じます。


宣言

void dispatch_io_close( dispatch_io_t channel, dispatch_io_close_flags_t flags);


パラメーター

channel閉じるべきチャンネル。
flagsチャネルを閉じる時使用するオプション。可能な値のリストについては、チャンネル閉鎖オプション を参照してください。

議論

この関数を呼び出した後、チャンネル上のより多くの読み書き操作をスケジュールしないでください。そうすると、エラーがあなたのハンドラに送信されます。


DISPATCH_IO_STOP オプションが flags パラメーターで指定された場合、システムは未処理の I/O チャンネルの読み書き操作を中断しようとします。このフラグを指定しても、対応するハンドラは、部分的な結果で呼び出されます。また、ハンドラの最後の呼び出しは操作が中断されたことを示す ECANCELED エラーコードが渡されます。DISPATCH_IO_STOP フラグを指定しない場合、読み書き操作は、通常どおり完了までチャンネルで実行します。




指定されたチャンネル上でバリア操作をスケジュールします。


宣言

void dispatch_io_barrier( dispatch_io_t channel, dispatch_block_t barrier);


パラメーター

channelその上でバリアをスケジュールしたいチャンネル。
barrierチャンネル上のすべての以前スケジュールされた操作が完了したときに実行すべきブロック。

議論

バリア操作は、以前のすべての操作が完了し、指定された barrier ブロックが実行されするまで新しいチャンネルに関連する操作が実行されないことを確認する方法です。バリア操作は、チャンネルのファイル記述子に適用され、指定されたチャンネルには適用されません。言い換えると、複数のチャンネルが、同じファイル記述子に関連付けられている場合、チャネルのいずれかにスケジュールされたバリア操作は、すべてのチャネルにわたってバリアとして作用します。バリアブロックが実行される前に、これらのチャンネルのいずれかの上の、以前にスケジュールされた全ての操作を完了する必要があります。


バリアブロックが実行されている間、fsync、lseek、および同様の関数を使用したチャンネルの基礎となるファイル記述子には安全に操作できますが、ブロックはファイル記述子を決して閉じてはいけません。




ハンドラブロックをキューに入れる前に、処理できる最大バイト数を設定します。


宣言

void dispatch_io_set_high_water( dispatch_io_t channel, size_t high_water);


パラメーター

channelその high-water マークを構成したいチャンネル。
high_water対応する I/O ハンドラブロックをキューに入れる前に読み書きすべき最大バイト数。

議論

読み書き操作中に、チャンネルは、関連するハンドラブロックをキューに入れる頻度を決定するために、high-wager および low-water マーク値を使用します。読み書きされたバイト数は、これらの 2 つの値の間にある時には、ブロックをキューに入れます。


チャンネルのデフォルトの high-water マークは SIZE_MAX に設定されています。


以下も見よ

dispatch_io_set_low_water



ハンドラブロックをキューに入れる前に、プロセスへの最小バイト数を設定します。


宣言

void dispatch_io_set_low_water( dispatch_io_t channel, size_t low_water);


パラメーター

channelその low-water マークを構成したいチャンネル。
low_water対応する I/O ハンドラブロックをキューに入れる前に読み書き込みするべき最小バイト数。

議論

読み書き操作中に、チャンネルは、関連するハンドラブロックをキューに入れる頻度を決定するために、high-water および low-water マーク値を使用します。読み書きされたバイト数が、これらの 2 つの値の間にある時には、ブロックをキューに入れます。EOF に達したか、チャネル間隔が DISPATCH_IO_STRICT_INTERVAL フラグが設定されている時だけ、バイト数は low-water マーク未満できます。


実際には、あなたのハンドラは、現在の low-water マークよりも有意に大きいデータ・ブロックを処理するように設計されるべきです。常にあなたのハンドラで、同じ量のデータを処理したい場合は、low-water および high-water マークを同じ値に設定して下さい。


チャンネルのデフォルトの low-water マークは指定されていません。しかし、デフォルトの値であっても、部分的な結果が返ることがあることを想定する必要があります。部分的な結果の戻り値を防止したい場合は、low-water マークを SIZE_MAX に設定します。


以下も見よ

dispatch_io_set_high_water



そこでチャンネルの I/O ハンドラを起動する(ナノセカンドで) 間隔を設定します。


宣言

void dispatch_io_set_interval( dispatch_io_t channel, uint64_t interval, dispatch_io_interval_flags_t flags);


パラメーター

channelその間隔を構成したいチャンネル。
interval全ての I/O ハンドラのスケジュールが望まれる前に経過しなければならないナノセカンド数。
flags時間間隔で望みの配信動作を示すフラグ。フラグのリストについては、チャンネル構成オプション を参照してください。

議論

読み書き操作の状態に定期的に進捗レポートを受信するためにはチャンネル間隔がその方法です。プログレスバーや、アプリケーションの他の部分を更新するには、このフィードバックを使用できます。


チャンネル上の間隔を設定した場合、任意の読み書き操作のためのハンドラが、処理されたデータの量が、チャンネルの現在の low-lwater マークを上回っている場合にのみ与えられた間隔でキューに入れられます。flags パラメーターに DISPATCH_IO_STRICT_INTERVAL 定数を渡すと、low-water マークを超えていない場合でも、ハンドラを強制的にキューに入れます。


システムは他のシステムアクティビティとハンドラの配信を揃えるために、指定された間隔に少しの余裕を追加できます。この動作の目的は、システム全体の性能や消費電力を改善することです。




指定されたチャンネルに関連したファイル記述子を返します。


宣言

dispatch_fd_t dispatch_io_get_descriptor( dispatch_io_t channel);


パラメーター

channelそのファイル記述子を取得したいチャンネル。

戻り値

チャンネルに関連付けられたファイル記述し、またはファイル記述しがまだ開いないか閉じている時は -1。


議論

チャンネルに関連付けられているパス名がまだ開かれていない場合、この関数を呼び出すと、通常は一つの例外を除いて、対応するファイルを開けません。チャンネル上でスケジュールしたバリアブロックからこの関数を呼び出す場合、この関数はファイルを開き、結果のファイル記述子を返します。




ディスパッチデータオブジェクトの管理


ディスパッチデータオブジェクトは、メモリに基礎を置いたデータバッファを管理するためのインターフェースを表します。データバッファにアクセスするクライアントは、メモリの連続ブロックとして、それを参照しますが、内部バッファはメモリの不連続な複数のブロックから構成されているかもしれません。




指定されたメモリ・バッファを持つ、新しいディスパッチデータオブジェクトを作成します。


宣言

dispatch_data_t dispatch_data_create( const void *buffer, size_t size, dispatch_queue_t queue, dispatch_block_t destructor);


パラメーター

bffer望みのデータを含むメモリの近接したバッファ。
sizeバイト単位で測定した buffer のサイズ。
queueデータオブジェクトを解放する時間のときにその上で destructor を呼び出すキュー。キューは、データオブジェクトによって保持されます。
destructorデータ・オブジェクトに関連付けられたメモリを解放する責任があるブロック。システムに提供された destructor を表す定数のリストについては、データを破壊する定数 を参照してください。

戻り値

望みのデータを含む新しいデータオブジェクト。このオブジェクトは、最初は保持されます。それを使用して行われた時、データオブジェクトを解放するのはあなたに責任があります。


buffer が NULL であるか、サイズが 0 の場合、この関数は空のディスパッチオブジェクトを返します。


議論

DISPATCH_DATA_DESTRUCTOR_DEFAULT 定数を使用して、デフォルトのデストラクタを指定した場合、この関数は、buffer 内のデータのコピーを作成し、そのデータを内部的に管理します。他の値を指定した場合、この関数はあなたのバッファへのポインタを保存し、あなたが提供するデストラクタにそのバッファを解放する責任を残します。


あなたがオブジェクトへの最後の参照を解放すると、システムは、一般的に提供したキュー上のデストラクタ内のブロックをキューに入れます。しかし、デストラクタのため DISPATCH_DATA_DESTRUCTOR_FREE 定数を指定する場合は、システムは単に関連するメモリインラインを解放します。




ディスパッチデータオブジェクトによって管理されたメモリの論理サイズを返します。


宣言

size_t dispatch_data_get_size( dispatch_data_t data);


パラメーター

data照会するべきディスパッチデータオブジェクト

戻り値

データ・オブジェクトによって表されるバイト数。


議論

複数の非連続メモリ領域を表すデータオブジェクトの場合、この機能によって報告されたサイズは、個々の領域のサイズの合計です。




指定されたオブジェクトのメモリの近接した表現を含む新しいディスパッチデータオブジェクトを返します。


宣言

dispatch_data_t dispatch_data_create_map( dispatch_data_t data, const void **buffer_ptr, size_t *size_ptr);


パラメーター

dataマッピングするメモリを含むディスパッチデータオブジェクト。オブジェクトが複数の近接しないメモリ領域を含んでいる場合は、それらの領域は、新しいオブジェクトの単一の近接したメモリ領域にコピーされます。
buffer_ptr入力時には、新しく作成されたディスパッチデータオブジェクトのメモリ領域へのポインタを保存する変数へのポインタ。この情報を必要としない場合は、このパラメータに NULL を指定できます。
size_ptr入力時には、新しく作成されたディスパッチデータオブジェクト内の近接したメモリ領域のサイズを保存する変数へのポインタ。この情報を必要としない場合は、このパラメータに NULL を指定できます。

戻り値

data パラメータ内のオブジェクトによって管理されるメモリの近接バージョンを含む新しいディスパッチデータオブジェクト。


議論

buffer_ptr または size_ptr に NULL でない値を指定した場合、それらの変数に返される値は、新しく作成されたディスパッチデータオブジェクトを解放するまでの間だけ有効です。新しいデータオブジェクトのデータにアクセスするための簡単な方法として、これらの値を使用できます。




他の二つのデータオブジェクトから連結したデータからなる新たなディスパッチデータオブジェクトを返します。


宣言

dispatch_data_t dispatch_data_create_concat( dispatch_data_t data1, dispatch_data_t data2);


パラメーター

data1含めるべき最初のデータオブジェクト。このオブジェクトからのメモリは、新しいデータオブジェクトのメモリー領域の先頭に配置されています。
data2含めるべき第二のデータオブジェクト。このオブジェクトからのメモリは、data1 からメモリの最後に追加されます。

戻り値

連結されたメモリを含む新しいディスパッチデータオブジェクト。


議論

この関数を呼び出した後、data1 または data2 内のオブジェクトのいずれかを解放しても安全です。しかし、新たに作成されたディスパッチデータオブジェクトがそれを参照している場合、それをコピーするのとは対照的に、それらのオブジェクトからメモリは、割り当て解除されない場合がありますのでご注意ください。




そのコンテンツは、別のオブジェクトのメモリ領域の部分から構成された、新しいディスパッチデータオブジェクトを返します。


宣言

dispatch_data_t dispatch_data_create_subrange( dispatch_data_t data, size_t offset, size_t length);


パラメーター

data新しいオブジェクトに使用すべき、オリジナルのメモリを含むディスパッチデータオブジェクト。
offsetdata のメモリへのバイトオフセット。このオフセットは、新しいオブジェクトのメモリの開始点マークします。
lengthoffset から新しいオブジェクトを含むバイト数。

戻り値

そのメモリが data パラメータ内のオブジェクトに関連付けられたメモリの部分範囲である新しいディスパッチデータオブジェクト。


議論

この関数を呼び出した後、data 内のオブジェクトを解放するのは安全です。しかし、そのオブジェクトからのメモリは、新しく作成されたディスパッチデータオブジェクトがそれを参照している場合、それをコピーするのとは対照的に、直ちに割り当て解除されない場合がありますのでご注意ください。




ディスパッチデータオブジェクトのメモリを横断し、各地域のカスタムコードを実行します。


宣言

bool dispatch_data_apply( dispatch_data_t data, dispatch_data_applier_t applier);


パラメーター

dataそのメモリを使用したいディスパッチオブジェクト。
applierdata の各近接したメモリ領域で実行すべきブロック。

戻り値

横断がうまく完了したかどうかを示すブール値。applier ブロックは領域の全てで実行されたかまたは横断するものが何もなかった場合、通常、この値は true です。それが false の場合、ブロックが横断を早く終了した事を意味します。


議論

各々の近接したメモリ領域については、この機能は一時的なディスパッチデータオブジェクトを作成し、指定されたアプライヤーの関数に渡します。この新しいオブジェクト、およびブロックへの他のパラメータは、検査されている特定のメモリ領域への直接アクセスを提供します。アプライヤーブロックが一旦戻ると、一時的なディスパッチデータオブジェクトは解放されます。(data パラメータのオリジナルのオブジェクトは触れられません。)



注意： ディスパッチデータオブジェクトがゼロの長さの場合は、アプライヤーブロックは呼び出されません。




別のデータオブジェクト内のデータの一部を含むデータオブジェクトを返します。


宣言

dispatch_data_t dispatch_data_copy_region( dispatch_data_t data, size_t location, size_t *offset_ptr);


パラメーター

date照会すべきディスパッチデータオブジェクト。
locationどのメモリ領域を返すか決定する際に使用するバイトオフセット。
offset_ptr入力時の、変数へのポインタ。出力時に、この変数は返されたメモリ領域の data の先頭からのオフセットを含んでいます。

戻り値

指定された場所を含む全メモリ領域のコピーを含むディスパッチデータオブジェクト。




時間の管理




デフォルトのクロックに相対 dispatch_time_t を作成したり、既存の dispatch_time_t を変更します。


宣言

dispatch_time_t dispatch_time( dispatch_time_t when, int64_t delta);


パラメーター

when新しい値のための基礎として使用するべき dispatch_time_t 値。今への新しい時間相対値を作成するには DISPATCH_TIME_NOW を渡します。
deltawhen パラメータで時刻に加えるべきナノセカンド数。

戻り値

新しい dispatch_time_t。


議論

デフォルトのクロックは mach_absolute_time に基づいています。




ウォールクロックに従って絶対時間を使用して dispatch_time_t を作成します。


宣言

dispatch_time_t dispatch_walltime( const struct timespec *when, int64_t delta);


パラメーター

when時間を追加すべき struct timespec。NULL が渡された場合、この関数は、gettimeofday の結果を使用します。
delta追加されるべきナノセカンド単位の時間。

戻り値

新しい dispatch_time_t。


議論

ウォールクロックは、gettimeofday に基づいています。




キュー特有のコンテキストデータの管理




指定されたディスパッチキュー用のキー／値のデータを設定します。


宣言

void dispatch_queue_set_specific(dispatch_queue_t queue, const void* key, void *context, dispatch_function_t destructor);


パラメーター

queueその上で指定されたキー／値のデータを設定すべきキュー。このパラメータは NULL であってはいけません。
key関連付けられたコンテキストデータを識別するために使用したいキー。キーはポインタとしてだけ比較され、逆参照されることは決してありません。したがって、特定のサブシステムまたはあなたが一意の値を識別できるようにする他の値の静的変数へのポインタを使用できます。文字列定数へのポインタを指定することは推奨されません。NULL は、キーの有効な値ではなく、NULL キーでコンテキストデータを設定しようとしても無視されます。
contextkeyに関連付けられたコンテキストデータ。このパラメータは NULL を指定できます。
destructorあなたのコンテキストデータを解放するために使用できるデストラクタ関数。このパラメータは NULL を指定できます。context が NULL の場合、あなたのデストラクタ関数は無視されます。

議論

ディスパッチキューにカスタムコンテキストデータを関連付けるために、このメソッドを使用して下さい。キュー上で実行するブロックは、それらが実行されているうちに、このデータを取得するために dispatch_get_specific 関数を使用できます。


以下も見よ

dispatch_queue_get_specific



指定されたディスパッチキューに関連付けられたキーの値を取得します。


宣言

void* dispatch_queue_get_specific(dispatch_queue_t queue, const void *key);


パラメーター

queue望みのコンテキストデータを含むキュー。このパラメータは NULL であってはいけません。
key関連するコンテキストデータを識別するキー。キーはポインタとしてだけ比較され、逆参照されることは決してありません。したがって、特定のサブシステムまたはあなたが一意の値を識別できるようにする他の値の静的変数へのポインタを使用できます。文字列定数へのポインタを指定することは推奨されません。

戻り値

key に関連付けられたコンテキストデータが、またはコンテンツが見つからなかった場合 NULL。


議論

特定のディスパッチキューに関連付けられたコンテキストデータを取得するために、このメソッドを使用できます。キュー上で実行されるブロックは、その特定のキューに関連付けられたコンテキストを取得するために dispatch_get_specific 関数を代わりに使用できます。


以下も見よ

dispatch_queue_set_specific



現在のディスパッチキューに関連付けられたキーの値を返します。


宣言

void* dispatch_get_specific(const void *key);


パラメーター

keyその上で現在のブロックが実行されているディスパッチキューに関連付けられたキー。キーはポインタとしてのみ比較され、逆参照されることは決してありません。文字列定数を直接渡すのはお勧めしません。

戻り値

指定されたキーのコンテキスト値。それ以外の場合、キュー(またはそのターゲット・キュー) に設定されるか、またはキューがグローバルな同時キューの場合 NULL。


議論

この関数は、ディスパッチキューで実行しているブロックから呼び出されることを意図しています。キューに関連付けられたコンテキストデータを取得するためにそれを使用して下さい。コンテキストを提供するために、キューが全く存在しないため、ディスパッチキューで実行されていないコードからこのメソッドを呼び出すと、NULL を返します。




データ型




ディスパッチキューに提出されたブロックのプロトタイプであり、これは引数を取らず、戻り値はありません。


宣言

typedef void (^dispatch_block_t)(
   void);


議論

ブロックの宣言は、スタック上の記憶装置を割り当てます。したがって、この例では、無効な構築物を、示しています。


1.dispatch_block_t block;
2.
3.if (x) {
4.    block = ^{printf("true\n"); };
5.} else {
6.    block = ^{printf("false\n"); };
7.}
8.block();  // unsafe!!


何が舞台裏で起こっているかと言うと：


1.if (x) {
2.    struct Block __tmp_1 = ...;  // setup details
3.    block = &__tmp_1;
4.}  else {
5.    struct Block __tmp_2 = ...; // setup details
6.    block = &__tmp_2;
7.}


例が示すように、スタック変数のアドレスは、それが割り当てられた範囲を逸脱しています。


Import 文




ディスパッチキューに提出される関数のプロトタイプ。


宣言

typedef void (*dispatch_function_t)(void *);


議論

パラメータとして dispatch_function_t 型をとる関数はまた、あなたが提供するコンテキストデータへのポインタも取ります。あなたのディスパッチ関数が呼び出されると、そのコンテキストデータへのポインタが関数にパラメータとして渡されます。コンテキストデータへのポインタがあなたの関数に変更されずに渡されると、あなたにはポインタが有効であることを確認する責任があります。


Import 文




非同期呼び出しのためキューに提出されたブロックオブジェクトのグループ。


宣言

typedef struct dispatch_group_s *dispatch_group_t;


議論

ディスパッチグループは、ブロックのセットをモニターするためのメカニズムです。あなたのアプリケーションは、必要に応じて、同期的または非同期的にグループ内のブロックをモニターできます。拡張機能では、グループは他のタスクの完了に依存するコードを同期させるために有用です。


グループ内のブロックは、異なるキュー上で実行することができ、それぞれ個別のブロックがグループに、より多くのブロックを追加できることに注意して下さい。


ディスパッチグループは、どれだけ多くのブロックが残っているかを追跡し、GCD は、関連するすべてのブロックを完全に実行するまでグループを保持します。


Import 文




すべての GCD ディスパッチオブジェクト関数で使用するためのポリモーフィックオブジェクトタイプ。


宣言

typedef union {
   struct dispatch_object_s *_do;
   struct dispatch_continuation_s *_dc;
   struct dispatch_queue_s *_dq;
   struct dispatch_queue_attr_s *_dqa;
   struct dispatch_group_s *_dg;
   struct dispatch_source_s *_ds;
   struct dispatch_source_attr_s *_dsa;
   struct dispatch_semaphore_s *_dsema;
   struct dispatch_data_s *_ddata;
   struct dispatch_io_s *_dchannel;
   struct dispatch_operation_s *_doperation;
   struct dispatch_fld_s *_dfld;
} dispatch_object_t __attribute__((transparent_union));


議論

ディスパッチオブジェクトは、メモリ管理、中断、キャンセルやコンテキストポインタを調整するための関数を共有しています。ディスパッチ・フレームワークでの作成関数によって返されたオブジェクトは、それぞれ、dispatch_retain と dispatch_release 関数で一様に保持し、解放できます。GCD は、全てのクライアントが与えられたオブジェクトへの最後または唯一の参照を持っていることを保証しません。オブジェクトは、システムによって内部に保持されるかもしれません。



注意： 上記の複雑な宣言は、ヘッダファイルからのものですが、簡略化のため、以下のようにするのを検討して下さい。

typedef void *dispatch_object_t;


Import 文




dispatch_once 関数で使用するための断言。


宣言

typedef long dispatch_once_t;


議論

この型の変数は、グローバルまたは静的スコープを持っていなければなりません。自動または動的な割り当てで、この型を使用した結果は未定義です。詳細については、dispatch_once を参照してください。


Import 文




ディスパッチキューは、アプリケーションが、その後の実行のためブロックを提出した軽量オブジェクトです。


宣言

typedef struct dispatch_queue_s *dispatch_queue_t;


議論

ディスパッチキューは、シリアルに FIFO 順でそれに提出したブロックを呼び出します。シリアル・キューは、一度に 1 つだけのブロックを呼び出しますが、独立したキューはそれぞれ、互いに対して同時にそれらのブロックを呼び出すことができます。


グローバル同時キューは FIFO 順でブロックを呼び出しますが、複数のブロックを同時に呼び出すことができるように、彼らの完了を待ちません。


システムは、ディスパッチキューを処理し、それらに提出されたブロックを呼び出すスレッドのプールを管理します。概念的には、ディスパッチキューは、実行する独自のスレッドがあるか、またキューの間の相互作用は高度に非同期です。


ディスパッチキューは dispatch_retain と dispatch_release を経由して参照がカウントされます。それらが終了するまでキューに送信された保留中のブロックは、キューへの参照も保持します。キューへのすべての参照が解放されると、キューはシステムによって割り当て解除されます。


Import 文




時間のやや抽象的な表現。


宣言

typedef uint64_t dispatch_time_t;


議論

可能な値のリストについては、ディスパッチ時間定数 を参照して下さい。


Import 文




ディスパッチソースによってモニターされているシステムオブジェクトの型識別子。


宣言

typedef const struct dispatch_source_type_s *dispatch_source_type_t;


議論

この型の定数は、ディスパッチソースによってモニターされている、低レベルのシステム・オブジェクトのクラスを表します。この型の定数は dispatch_source_create にパラメータとして渡され、ハンドル引数がどのように解釈されるか(ファイル記述子、mach ポート、シグナル数、プロセス識別子などのように) を決定し、マスク引数がどのように解釈されるかを決定します。ソース型定数の詳細については、ディスパッチ・ソース型の定数 を参照してください。


Import 文




I/O 操作に使用されるファイル記述子。


宣言

typedef int dispatch_fd_t;


Import 文




メモリの近接した、またはまばらな領域を表す不変オブジェクト。


宣言

typedef dispatch_data_s *dispatch_data_t;


議論

データ・オブジェクト内のメモリへの直接アクセスは、そのメモリを変更してはなりません。


Import 文




データ・オブジェクト内のすべての近接したメモリ領域に対して起動すべきブロック。


宣言

typedef bool (^dispatch_data_applier_t)(dispatch_data_t region,
   size_t offset,
   const void *buffer,
   size_t size);


議論

ディスパッチデータアプライヤーブロックのパラメータは以下のとおりです。


region分析されている現在のメモリ領域を含むデータオブジェクト。
offsetデータオブジェクトの開始から現在の領域への論理オフセット。
buffer現在の領域用のメモリへのポインタ。
size現在の領域用のメモリのサイズ。

このハンドラは、領域の横断を継続すべきかどうかを示すブール値を返します。


Import 文




ディスパッチ I/O チャンネル。


宣言

typedef dispatch_io_s *dispatch_io_t;


議論

ディスパッチ I/O チャンネルは、ファイル記述子とそのファイル記述子に適用される非同期の I/O ポリシーを表します。ディスパッチ I/O チャンネルは、ディスパッチオブジェクトの標準的な型であり、保持、解放、一時停止、そしてそれに応じて再開することができます。


Import 文




ディスパッチ I/O チャンネル上の操作を処理するために使用されるハンドラブロック。


宣言

typedef void (^dispatch_io_handler_t)(bool done, dispatch_data_t data, int error);


議論

ディスパッチ I/O ハンドラのパラメータは以下のとおりです。


done操作が完了したかどうかを示すフラグ。
data処理されるべきデータオブジェクト。このオブジェクトは、ハンドラの実行の期間中に、システムによって保持され、ハンドラブロックが返る時に解放されます。
error操作のために報告されたエラー番号(もしあれば)。0 のエラー番号は、通常、操作が成功したことを示します。

Import 文




ディスパッチ I/O チャンネルの型


宣言

typedef unsigned long dispatch_io_type_t;


Import 文




チャンネルのため閉じるオプションを指定するために使用されるフラグの型。


宣言

typedef unsigned long dispatch_io_close_flags_t;


Import 文




チャンネルのディスパッチ間隔を指定するために使用されるフラグの型。


宣言

typedef unsigned long dispatch_io_interval_flags_t;


Import 文




定数


dispatch_queue_priority_t


適切なグローバルの同時キューを選択するために使用します。


宣言

#define DISPATCH_QUEUE_PRIORITY_HIGH        2
#define DISPATCH_QUEUE_PRIORITY_DEFAULT     0
#define DISPATCH_QUEUE_PRIORITY_LOW         (-2)
#define DISPATCH_QUEUE_PRIORITY_BACKGROUND  INT16_MIN


定数

バックグラウンドの優先度で実行するキューに派遣した項目。キューは、すべての高い優先度のキューがスケジュールされた後に実行するようにスケジュールされ、システムは、その優先度がバックグラウンド状態に設定されたスレッド上の項目を実行します。このようなスレッドは、最も低い優先度であり、全てのディスク I/O は、システムへの影響を最小限に抑えるために振り絞られます。




dispatch_source_mach_send_flags_t


Mach が送信したイベントフラグ。


宣言

#define DISPATCH_MACH_SEND_DEAD 0x1


定数



dispatch_source_proc_flags_t


プロセス・イベントのフラグ。


宣言

#define DISPATCH_PROC_EXIT     0x80000000
#define DISPATCH_PROC_FORK     0x40000000
#define DISPATCH_PROC_EXEC     0x20000000
#define DISPATCH_PROC_SIGNAL   0x08000000


定数



dispatch_source_vnode_flags_t


ファイルシステムオブジェクトのイベントフラグ。


宣言

#define DISPATCH_VNODE_DELETE   0x1
#define DISPATCH_VNODE_WRITE    0x2
#define DISPATCH_VNODE_EXTEND   0x4
#define DISPATCH_VNODE_ATTRIB   0x8
#define DISPATCH_VNODE_LINK     0x10
#define DISPATCH_VNODE_RENAME   0x20
#define DISPATCH_VNODE_REVOKE   0x40


定数



dispatch_source_memorypressure_flags_t


メモリ圧迫イベントフラグ


宣言

#define DISPATCH_MEMORYPRESSURE_NORMAL      0x01
#define DISPATCH_MEMORYPRESSURE_WARN        0x02
#define DISPATCH_MEMORYPRESSURE_CRITICAL    0x04


定数



データオブジェクト定数


データ・オブジェクトを表す定数。


宣言

#define dispatch_data_empty


定数



データを破壊する定数


データオブジェクトに使用する破壊を表す定数。


宣言

#define DISPATCH_DATA_DESTRUCTOR_DEFAULT NULL
#define DISPATCH_DATA_DESTRUCTOR_FREE


定数



ディスパッチキューの型


新しいディスパッチキューを作成するときに使用する属性。


宣言

#define DISPATCH_QUEUE_SERIAL 
#define DISPATCH_QUEUE_CONCURRENT


定数

議論

あなたが作成したいディスパッチキューの型を指定するには、dispatch_queue_create 関数でこれらの定数を使用して下さい。その関数の attr パラメータにこれらの定数のいずれか一つを渡します。




ディスパッチ・ソース型の定数


ディスパッチソースの型。


宣言

#define DISPATCH_SOURCE_TYPE_DATA_ADD 
#define DISPATCH_SOURCE_TYPE_DATA_OR 
#define DISPATCH_SOURCE_TYPE_MACH_RECV 
#define DISPATCH_SOURCE_TYPE_MACH_SEND 
#define DISPATCH_SOURCE_TYPE_PROC 
#define DISPATCH_SOURCE_TYPE_READ 
#define DISPATCH_SOURCE_TYPE_SIGNAL 
#define DISPATCH_SOURCE_TYPE_TIMER 
#define DISPATCH_SOURCE_TYPE_VNODE 
#define DISPATCH_SOURCE_TYPE_WRITE 
#define DISPATCH_SOURCE_TYPE_MEMORYPRESSURE


定数



ディスパッチ時間定数


基本となる時間の定数。


宣言

#define DISPATCH_TIME_NOW 0
#define DISPATCH_TIME_FOREVER (~0ull)


定数



時間の倍率定数


時間の値を計算するための倍率。


宣言

#define NSEC_PER_SEC 1000000000ull
#define USEC_PER_SEC 1000000ull
#define NSEC_PER_USEC 1000ull


定数是正



ディスパッチ I/O チャンネルの型


作成されうるディスパッチ I/O チャンネルの型。


宣言

#define DISPATCH_IO_STREAM 0
#define DISPATCH_IO_RANDOM 1


定数



チャンネル閉鎖オプション


ディスパッチ I/O チャンネルを閉鎖する時使うオプション。


宣言

#define DISPATCH_IO_STOP 0x1


定数



チャンネル構成オプション


チャンネルを構成する時使用するオプション。


宣言

#define DISPATCH_IO_STRICT_INTERVAL 0x1


定数



次の章
目次
Xcode の新機能
  • GCD リファレンス
  • 概観
    • GGCD オブジェクトと自動参照カウント
  • 関数
  • キュー(待ち行列)の作成と管理
    • dispatch_get_main_queue
    dispatch_get_global_queue
    dispatch_queue_create
    dispatch_get_current_queue
    dispatch_queue_attr_make
    _with_qos_class
    dispatch_queue_get_label
    dispatch_set_target_queue
    dispatch_main
  • ディスパッチ用のキューのタスク
    • dispatch_async
    dispatch_async_f
    dispatch_sync
    dispatch_sync_f
    dispatch_after
    dispatch_after_f
    dispatch_apply
    dispatch_apply_f
    dispatch_once
    dispatch_once_f
  • ディスパッチグループの使用
    • dispatch_group_async
    dispatch_group_async_f
    dispatch_group_create
    dispatch_group_enter
    dispatch_group_leave
    dispatch_group_notify
    dispatch_group_notify_f
    dispatch_group_wait
  • ディスパッチオブジェクトの管理
    • dispatch_debug
    dispatch_get_context
    dispatch_release
    dispatch_resume
    dispatch_retain
    dispatch_set_context
    dispatch_set_finalizer_f
    dispatch_suspend
  • 手旗信号の使用
    • dispatch_semaphore_create
    dispatch_semaphore_signal
    dispatch_semaphore_wait
  • バリアの使用
    • dispatch_barrier_async
    dispatch_barrier_async_f
    dispatch_barrier_sync
    dispatch_barrier_sync_f
  • ディスパッチソースの管理
    • dispatch_source_cancel
    dispatch_source_create
    dispatch_source_get_data
    dispatch_source_get_handle
    dispatch_source_get_mask
    dispatch_source_merge_data
    dispatch_source_set_registration_handler
    dispatch_source_set_registration_handler_f
    dispatch_source_set_cancel_handler
    dispatch_source_set_cancel_handler_f
    dispatch_source_set_event_handler
    dispatch_source_set_event_handler_f
    dispatch_source_set_timer
    dispatch_source_testcancel
  • ディスパッチ I/O コンビニエンス API を使用して
    • dispatch_read
    dispatch_write
  • ディスパッチ I/O チャンネル API を使用して
    • dispatch_io_create
    dispatch_io_create_with_path
    dispatch_io_create_with_io
    dispatch_io_read
    dispatch_io_write
    dispatch_io_close
    dispatch_io_barrier
    dispatch_io_set_high_water
    dispatch_io_set_low_water
    dispatch_io_set_interval
    dispatch_io_get_descriptor
  • ディスパッチデータオブジェクトの管理
    • dispatch_data_create
    dispatch_data_get_size
    dispatch_data_create_map
    dispatch_data_create_concat
    dispatch_data_create_subrange
    dispatch_data_apply
    dispatch_data_copy_region
  • 時間の管理
    • dispatch_time
    dispatch_walltime
  • キュー特有のコンテキストデータの管理
    • dispatch_queue_set_specific
    dispatch_queue_get_specific
    dispatch_get_specific
  • データ型
    • dispatch_block_t
    dispatch_function_t
    dispatch_group_t
    dispatch_object_t
    dispatch_once_t
    dispatch_queue_t
    dispatch_time_t
    dispatch_source_type_t
    dispatch_fd_t
    dispatch_data_t
    dispatch_data_applier_t
    dispatch_io_t
    dispatch_io_handler_t
    dispatch_io_type_t
    dispatch_io_close_flags_t
    dispatch_io_interval_flags_t
  • 定数
    • dispatch_queue_priority_t
    dispatch_source_mach_send_flags_t
    dispatch_source_proc_flags_t
    dispatch_source_vnode_flags_t
    dispatch_source_memorypressure_flags_t
    データオブジェクト定数
    データを破壊する定数
    ディスパッチキューの型
    ディスパッチ・ソース型の定数
    ディスパッチ時間定数
    時間の倍率定数
    ディスパッチ I/O チャンネルの型
    チャンネル閉鎖オプション
    チャンネル構成オプション
    文書改定履歴












    トップへ(GCD リファレンス)












    トップへ(GCD リファレンス)












    トップへ(GCD リファレンス)












    トップへ(GCD リファレンス)












    トップへ(GCD リファレンス)












    トップへ(GCD リファレンス)












    トップへ(GCD リファレンス)












    トップへ(GCD リファレンス)












    トップへ(GCD リファレンス)












    トップへ(GCD リファレンス)












    トップへ(GCD リファレンス)












    トップへ(GCD リファレンス)