CreateIoCompletionPort 함수
I/O(입출력) 완료 포트를 만들고 지정된 파일 핸들에 연결하거나, 아직 파일 핸들에 연결되지 않은 I/O 완료 포트를 만들어 나중에 연결할 수 있습니다.
열린 파일 핸들의 인스턴스를 I/O 완료 포트와 연결하면 프로세스에서 해당 파일 핸들과 관련된 비동기 I/O 작업의 완료 알림을 받을 수 있습니다.
참고
여기에 사용된 파일 핸들이라는 용어는 디스크의 파일뿐만 아니라 겹치는 I/O 엔드포인트를 나타내는 시스템 추상화를 의미합니다. 네트워크 엔드포인트, TCP 소켓, 명명된 파이프 및 메일 슬롯과 같은 겹치는 I/O를 지원하는 모든 시스템 개체를 파일 핸들로 사용할 수 있습니다. 자세한 내용은 설명 섹션을 참조하세요.
구문
HANDLE WINAPI CreateIoCompletionPort(
_In_ HANDLE FileHandle,
_In_opt_ HANDLE ExistingCompletionPort,
_In_ ULONG_PTR CompletionKey,
_In_ DWORD NumberOfConcurrentThreads
);
매개 변수
-
FileHandle [in]
-
열려 있는 파일 핸들이거나 INVALID_HANDLE_VALUE입니다.
핸들은 겹치는 I/O를 지원하는 개체에 대한 핸들이어야 합니다.
핸들이 제공된 경우 겹치는 I/O 완료를 위해 열려 있어야 합니다. 예를 들어 CreateFile 함수를 사용하여 핸들을 가져올 때 FILE_FLAG_OVERLAPPED 플래그를 지정해야 합니다.
INVALID_HANDLE_VALUE를 지정하면 함수가 파일 핸들과 연결하지 않고 I/O 완료 포트를 만듭니다. 이 경우 ExistingCompletionPort 매개 변수는 NULL이어야 하며 CompletionKey 매개 변수는 무시됩니다.
-
ExistingCompletionPort [in, optional]
-
기존 I/O 완료 포트에 대한 핸들이거나 NULL입니다.
이 매개 변수가 기존 I/O 완료 포트를 지정하는 경우 함수는 이를 FileHandle 매개 변수로 지정된 핸들과 연결합니다. 함수는 성공하면 기존 I/O 완료 포트의 핸들을 반환하며 새 I/O 완료 포트를 만들지 않습니다.
이 매개 변수가 NULL인 경우 함수는 새 I/O 완료 포트를 만들고 FileHandle 매개 변수가 유효하면 이를 새 I/O 완료 포트와 연결합니다. 그러지 않으면 파일 핸들 연결이 발생하지 않습니다. 함수는 성공하면 새 I/O 완료 포트에 대한 핸들을 반환합니다.
-
CompletionKey [in]
-
지정된 파일 핸들에 대한 모든 I/O 완료 패킷에 포함된 핸들당 사용자 정의 완료 키입니다. 자세한 내용은 주의 섹션을 참조하세요.
-
NumberOfConcurrentThreads [in]
-
운영 체제에서 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 완료 포트 및 해당 핸들은 이를 만든 프로세스와 연결되며 프로세스 간에 공유할 수 없습니다. 그러나 단일 핸들은 동일한 프로세스의 스레드 간에 공유할 수 있습니다.
CreateIoCompletionPort는 세 가지 고유한 모드에서 사용할 수 있습니다.
- 파일 핸들과 연결하지 않고 I/O 완료 포트만 만듭니다.
- 기존 I/O 완료 포트를 파일 핸들과 연결합니다.
- 단일 호출로 만들기와 연결을 모두 수행합니다.
I/O 완료 포트를 연결하지 않고 만들려면 FileHandle 매개 변수는 INVALID_HANDLE_VALUE로, ExistingCompletionPort 매개 변수는 NULL로, CompletionKey 매개 변수는 0으로 설정합니다(이 경우 무시됨). NumberOfConcurrentThreads 매개 변수를 새 I/O 완료 포트에 대해 원하는 동시성 값으로 설정하거나 기본값(시스템의 프로세서 수)에 대해 0으로 설정합니다.
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 프로토콜 |
Yes |
SMB 3.0 TFO(투명 장애 조치(failover)) |
Yes |
SO(스케일 아웃 파일 공유)를 사용하는 SMB 3.0 |
Yes |
CsvFS(클러스터 공유 볼륨 파일 시스템) |
Yes |
ReFS(Resilient File System) |
Yes |
요구 사항
요구 사항 | 값 |
---|---|
지원되는 최소 클라이언트 |
Windows XP [데스크톱 앱 | UWP 앱] |
지원되는 최소 서버 |
Windows Server 2003 [데스크톱 앱 | UWP 앱] |
헤더 |
|
라이브러리 |
|
DLL |
|