CreateIoCompletionPort 関数 (ioapiset.h)

  • [アーティクル]

入力/出力 (I/O) 完了ポートを作成して、指定したファイル ハンドルに関連付けるか、ファイル ハンドルにまだ関連付けられていない I/O 完了ポートを作成して、後で関連付けることができます。

開かれたファイル ハンドルのインスタンスを I/O 完了ポートに関連付けると、そのファイル ハンドルに関わる非同期 I/O 操作の完了に関する通知をプロセスで受け取ることができます。

注  

ここで使用する "ファイル ハンドル" という用語は、ディスク上のファイルだけでなく、重複する I/O エンドポイントを表すシステム抽象化を指します。 ネットワーク エンドポイント、TCP ソケット、名前付きパイプ、メール スロットなど、重複する I/O をサポートするシステム オブジェクトは、ファイル ハンドルとして使用できます。 詳しくは、「解説」のセクションをご覧ください。

 

構文

HANDLE CreateIoCompletionPort(
  [in]           HANDLE    FileHandle,
  [in, optional] HANDLE    ExistingCompletionPort,
  [in]           ULONG_PTR CompletionKey,
  [in]           DWORD     NumberOfConcurrentThreads
);

パラメーター

[in] FileHandle

開いているファイル ハンドルまたは INVALID_HANDLE_VALUE。

ハンドルは、重複した I/O をサポートするオブジェクトに対するものである必要があります。

ハンドルが指定されている場合、このハンドルは、重複した I/O 完了のために開かれている必要があります。 たとえば、CreateFile 関数を使ってハンドルを取得する場合、FILE_FLAG_OVERLAPPED フラグを指定する必要があります。

INVALID_HANDLE_VALUE が指定されている場合、この関数は I/O 完了ポートをファイル ハンドルに関連付けずに作成します。 この場合、ExistingCompletionPort パラメーターは NULL でなければならず、CompletionKey パラメーターは無視されます。

[in, optional] ExistingCompletionPort

既存の I/O 完了ポートへのハンドルまたは NULL。

このパラメーターで既存の I/O 完了ポートが指定されている場合、関数は FileHandle パラメーターで指定されたハンドルに関連付けます。 関数が成功すると、既存の I/O 完了ポートのハンドルが返されます。新しい I/O 完了ポートは作成されません。

このパラメーターが NULL の場合、関数により新しい I/O 完了ポートが作成され、FileHandle パラメーターが有効な場合は、新しい I/O 完了ポートに関連付けられます。 それ以外の場合、ファイル ハンドルの関連付けは行われません。 関数が成功すると、新しい I/O 完了ポートにハンドルが返されます。

[in] CompletionKey

指定したファイル ハンドルのすべての I/O 完了パケットに含まれる、ハンドルごとのユーザー定義の完了キー。 詳細については、「解説」を参照してください。

[in] NumberOfConcurrentThreads

I/O 完了ポートの I/O 完了パケットを同時に処理することがオペレーティング システムで許容できるスレッドの最大数。 このパラメーターは、ExistingCompletionPort パラメーターが NULL でない場合、無視されます。

このパラメーターが 0 の場合、システム内のプロセッサと同じ数のスレッドを同時にシステムで実行できます。

戻り値

関数が成功した場合、戻り値は I/O 完了ポートへのハンドルです。

  • ExistingCompletionPort パラメーターが NULL だった場合、戻り値は新しいハンドルです。
  • ExistingCompletionPort パラメーターが有効な I/O 完了ポート ハンドルであった場合、戻り値はその同じハンドルです。
  • FileHandle パラメーターが有効なハンドルだった場合、そのファイル ハンドルは、返された I/O 完了ポートに関連付けられています。
関数が失敗した場合は、返される値は NULL です。 エラーの詳細情報を得るには、GetLastError 関数を呼び出します。

解説

I/O 完了通知パケットを I/O 完了ポートに送信するように、I/O システムに指示でき、このポートでパケットがキューに入れられます。 CreateIoCompletionPort 関数でこの機能が提供されます。

I/O 完了ポートとそのハンドルは、それを作成したプロセスに関連付けられ、プロセス間で共有することはできません。 ただし、1 つのハンドルを同じプロセス内のスレッド間で共有することはできます。

CreateIoCompletionPort は、次の 3 つの異なるモードで使用できます。

  • ファイル ハンドルに関連付けずに I/O 完了ポートのみを作成します。
  • 既存の I/O 完了ポートをファイル ハンドルに関連付けます。
  • 1 回の呼び出しで作成と関連付けの両方を実行します。
関連付けずに I/O 完了ポートを作成するには、FileHandle パラメーターを INVALID_HANDLE_VALUE に、ExistingCompletionPort パラメーターを NULL に、CompletionKey パラメーターを 0 (この場合は無視されます) に設定します。 NumberOfConcurrentThreads パラメーターを、新しい I/O 完了ポートの目的のコンカレンシー値に設定するか、既定値 (システム内のプロセッサ数) に 0 を設定します。

FileHandle パラメーターで渡されるハンドルには、重複した I/O をサポートする任意のハンドルを指定できます。 最も一般的なものとしては、FILE_FLAG_OVERLAPPED フラグを使って CreateFile 関数で開かれたハンドルがあります (ファイル、メール スロット、パイプなど)。 ソケットなどの他の関数によって作成されたオブジェクトも、I/O 完了ポートに関連付けられます。 ソケットの使用例については、「AcceptEx」を参照してください。 ハンドルは 1 つの I/O 完了ポートにのみ関連付けることができ、関連付けが行われた後、ハンドルは閉じられるまでその I/O 完了ポートに関連付けられたままになります。

I/O 完了ポートの理論、使用法、関連する関数の詳細については、「I/O 完了ポート」を参照してください。

ExistingCompletionPort パラメーター内の同じ I/O 完了ポート ハンドルと FileHandle パラメーター内の毎回異なるファイル ハンドルを使って CreateIoCompletionPort を複数回呼び出すことで、複数のファイル ハンドルを 1 つの I/O 完了ポートに関連付けることができます。

CompletionKey パラメーターを使用すると、どの I/O 操作が完了したかをアプリケーションで追跡できます。 この値は、CreateIoCompletionPort で機能制御に使用されません。代わりに、I/O 完了ポートとの関連付け時に FileHandle パラメーターで指定されたファイル ハンドルにアタッチされます。 この完了キーは、ファイル ハンドルごとに一意である必要があり、内部完了キュー プロセスの最後までファイル ハンドルに付随します。 これは、完了パケットの到着時に、GetQueuedCompletionStatus 関数の呼び出しで返されます。 CompletionKey パラメーターは、PostQueuedCompletionStatus 関数でも使用され、独自の特殊な目的の完了パケットをキューに入れます。

開いているハンドルのインスタンスが I/O 完了ポートに関連付けられた後は、ReadFileEx や WriteFileEx 関数では独自の非同期 I/O メカニズムがあるため、これらの関数でこれを使用することはできません。

ハンドルの継承や DuplicateHandle 関数の呼び出しを使って I/O 完了ポートに関連付けられているファイル ハンドルを共有しないことをお勧めします。 このような重複するハンドルを使って実行された操作により、完了通知が生成されます。 慎重に検討することをお勧めします。

I/O 完了ポート ハンドルと、その特定の I/O 完了ポートに関連付けられているすべてのファイル ハンドルは、"I/O 完了ポートの参照" と呼ばれます。 I/O 完了ポートの参照がなくなると、その I/O 完了ポートは解放されます。 したがって、I/O 完了ポートとそれに関連付けられているシステム リソースを解放するには、これらのハンドルをすべて適切に閉じる必要があります。 これらの条件が満たされたら、CloseHandle 関数を呼び出して I/O 完了ポート ハンドルを閉じます。

Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。

テクノロジ サポートされています
サーバー メッセージ ブロック (SMB) 3.0 プロトコル はい
SMB 3.0 Transparent Failover (TFO) はい
スケールアウト ファイル共有 (SO) を使う SMB 3.0 はい
クラスターの共有ボリューム ファイル システム (CsvFS) はい
Resilient File System (ReFS) はい

必要条件

   
サポートされている最小のクライアント Windows XP [デスクトップ アプリ | UWP アプリ]
サポートされている最小のサーバー Windows Server 2003 [デスクトップ アプリのみ | UWP アプリ]
対象プラットフォーム Windows
ヘッダー ioapiset.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

AcceptEx

CreateFile

DuplicateHandle

File Management 関数

関数

GetQueuedCompletionStatus

GetQueuedCompletionStatusEx

I/O 完了ポート

概要トピック

PostQueuedCompletionStatus

ReadFileEx

Windows ヘッダーの使用

Windows ソケット 2

WriteFileEx