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 앱]
헤더
IoAPI.h(Windows.h 포함);
Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP의 WinBase.h(Windows.h 포함)
라이브러리
Kernel32.lib
DLL
Kernel32.dll

참고 항목

개요 항목

파일 관리 함수

I/O 완료 포트

Windows 헤더 사용

Windows 소켓 2

함수

AcceptEx

CreateFile

DuplicateHandle

GetQueuedCompletionStatus

GetQueuedCompletionStatusEx

PostQueuedCompletionStatus

ReadFileEx

WriteFileEx