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 완료 포트와 연결됩니다.
설명
I/O 완료 알림 패킷을 큐에 대기 중인 I/O 완료 포트로 보내도록 I/O 시스템에 지시할 수 있습니다. CreateIoCompletionPort 함수는 이 기능을 제공합니다.
I/O 완료 포트 및 해당 핸들은 이를 만든 프로세스와 연결되며 프로세스 간에 공유할 수 없습니다. 그러나 단일 핸들은 동일한 프로세스의 스레드 간에 공유할 수 있습니다.
CreateIoCompletionPort는 세 가지 고유한 모드에서 사용할 수 있습니다.
- 파일 핸들과 연결하지 않고 I/O 완료 포트만 만듭니다.
- 기존 I/O 완료 포트를 파일 핸들과 연결합니다.
- 단일 호출로 만들기와 연결을 모두 수행합니다.
FileHandle 매개 변수에 전달된 핸들은 겹치는 I/O를 지원하는 모든 핸들이 될 수 있습니다. 가장 일반적으로 FILE_FLAG_OVERLAPPED 플래그를 사용하여 CreateFile 함수로 연 핸들입니다(예: 파일, 메일 슬롯 및 파이프). 소켓과 같이 다른 함수로 만든 개체도 I/O 완료 포트와 연결할 수 있습니다. 소켓을 사용하는 예제는 AcceptEx를 참조하세요. 핸들은 하나의 I/O 완료 포트에만 연결할 수 있으며 연결이 완료된 후 핸들은 닫힐 때까지 해당 I/O 완료 포트와 연결된 상태를 유지합니다.
I/O 완료 포트 이론, 사용 및 관련 함수에 대한 자세한 내용은 I/O 완료 포트를 참조하세요.
매번 ExistingCompletionPort 매개 변수의 동일한 I/O 완료 포트 핸들과 FileHandle 매개 변수의 다른 파일 핸들을 사용하여 CreateIoCompletionPort를 여러 번 호출함으로써 여러 파일 핸들을 단일 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 완료 포트 및 관련 시스템 리소스를 릴리스하려면 이러한 핸들을 모두 올바르게 닫아야 합니다. 이러한 조건이 충족되면 CloseHandle 함수를 호출하여 I/O 완료 포트 핸들을 닫습니다.
Windows 8 및 Windows Server 2012에서 이 함수는 다음 기술을 통해 지원됩니다.
| 기술 | 지원됨 |
|---|---|
| SMB(서버 메시지 블록) 3.0 프로토콜 | 예 |
| SMB 3.0 TFO(투명 장애 조치(failover)) | 예 |
| SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0 | Yes |
| CsvFS(클러스터 공유 볼륨 파일 시스템) | 예 |
| ReFS(Resilient File System) | 예 |
요구 사항
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱 | UWP 앱] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱 | UWP 앱] |
| 대상 플랫폼 | Windows |
| 헤더 | ioapiset.h(Windows.h 포함) |
| 라이브러리 | Kernel32.lib |
| DLL | Kernel32.dll |
참고 항목
함수
개요 항목