다음을 통해 공유

LPFN_RIOCREATECOMPLETIONQUEUE 콜백 함수(mswsock.h)

  • 아티클

RIOCreateCompletionQueue 함수는 Winsock 등록 I/O 확장에 사용할 특정 크기의 I/O 완료 큐를 만듭니다.

구문

LPFN_RIOCREATECOMPLETIONQUEUE LpfnRiocreatecompletionqueue;

RIO_CQ LpfnRiocreatecompletionqueue(
  DWORD QueueSize,
  PRIO_NOTIFICATION_COMPLETION NotificationCompletion
)
{...}

매개 변수

QueueSize

만들 완성 큐의 크기(항목 수)입니다.

NotificationCompletion

RIO_NOTIFICATION_COMPLETION 구조체의 Type 멤버(I/O 완료 또는 이벤트 알림)를 기반으로 사용할 알림 완료 유형입니다.

Type 멤버가 RIO_EVENT_COMPLETION 설정된 경우 RIO_NOTIFICATION_COMPLETION 구조체의 이벤트 멤버를 설정해야 합니다.

Type 멤버가 RIO_IOCP_COMPLETION 설정된 경우 RIO_NOTIFICATION_COMPLETION 구조체의 Iocp 멤버를 설정해야 하며 RIO_NOTIFICATION_COMPLETION구조체의 Iocp.Overlapped 멤버는 NULL이 아니어야 합니다.

NotificationCompletion 매개 변수가 NULL인 경우 이 매개 변수는 알림 완료가 사용되지 않음을 지정하며 완료를 결정하는 데 폴링을 사용해야 합니다.

반환 값

오류가 발생하지 않으면 RIOCreateCompletionQueue 함수는 새 완료 큐를 참조하는 설명자를 반환합니다. 그렇지 않으면 RIO_INVALID_CQ 값이 반환되고 WSAGetLastError 함수를 호출하여 특정 오류 코드를 검색할 수 있습니다.

반환 코드 설명
WSAEFAULT
 시스템이 호출에서 포인터 인수를 사용하려는 시도에서 잘못된 포인터 주소를 발견했습니다.
WSAEINVAL
 잘못된 매개 변수가 함수에 전달되었습니다.
이 오류는 QueueSize 매개 변수가 1보다 작거나 Mswsockdef.h 헤더 파일에 정의된 RIO_MAX_CQ_SIZE보다 큰 경우 반환됩니다.
WSAENOBUFS
 충분한 메모리를 할당할 수 없습니다. 이 오류는 QueueSize 매개 변수에 따라 요청된 완료 큐를 할당할 메모리가 부족한 경우 반환됩니다.

설명

RIOCreateCompletionQueue 함수는 특정 크기의 I/O 완료 큐를 만듭니다. 완료 큐의 크기는 완료 큐와 연결할 수 있는 등록된 I/O 소켓 집합을 제한합니다. 자세한 내용은 RIOCreateRequestQueue 함수를 참조하세요.

RIO_CQ 만들 때 NotificationCompletion 매개 변수가 가리키는 RIO_NOTIFICATION_COMPLETION 구조는 애플리케이션이 완료 큐 알림을 받는 방법을 결정합니다. 완료 큐를 만들 때 RIO_NOTIFICATION_COMPLETION 구조가 제공되는 경우 애플리케이션은 RIONotify 함수를 호출하여 완료 큐 알림을 요청할 수 있습니다. 일반적으로 이 알림은 완료 큐가 비어 있지 않을 때 발생합니다. 이 문제는 즉시 또는 다음 완료 항목이 완료 큐에 삽입될 때 발생할 수 있습니다. 그러나 보내기 및 수신 요청은 RIO_MSG_DONT_NOTIFY 플래그가 지정될 수 있습니다. 완료 큐 알림 및 는 이러한 요청의 결과로 트리거되지 않습니다. 완료 큐에 RIO_MSG_DONT_NOTIFY 플래그가 설정된 항목만 포함된 경우 완료 큐 알림이 트리거되지 않습니다. 또한 새 항목이 완료 큐에 들어가면 연결된 요청에 RIO_MSG_DONT_NOTIFY 플래그가 설정되지 않은 경우에만 완료 큐 알림이 트리거됩니다. RIODequeueCompletion 함수를 사용하여 폴링하여 완료된 모든 요청을 계속 검색할 수 있습니다. 완료 큐 알림이 실행되면 애플리케이션은 다른 완료 큐 알림을 받으려면 RIONotify 함수를 호출해야 합니다. 완료 큐 알림이 발생하면 애플리케이션은 일반적으로 RIODequeueCompletion 함수를 호출하여 완료된 송신 또는 수신 요청을 큐에서 제거합니다.

완료 큐 알림에는 두 가지 옵션을 사용할 수 있습니다.

  • 이벤트 핸들.
  • I/O 완료 포트

RIO_NOTIFICATION_COMPLETION 구조의 Type 멤버가 RIO_EVENT_COMPLETION 설정된 경우 이벤트 핸들을 사용하여 완료 큐 알림을 보냅니다. 이벤트 핸들은 RIOCreateCompletionQueue 함수에 전달된 RIO_NOTIFICATION_COMPLETION 구조체에서 EventNotify.EventHandle 멤버로 제공됩니다. Event.EventHandle 멤버에는 WSACreateEvent 또는 CreateEvent 함수에서 만든 이벤트에 대한 핸들이 포함되어야 합니다. RIONotify 완료를 받으려면 애플리케이션이 WSAWaitForMultipleEvents 또는 유사한 대기 루틴을 사용하여 지정된 이벤트 핸들을 대기해야 합니다. 이 RIO_CQ대한 RIONotify 함수가 완료되면 이벤트가 발생합니다. RIOCreateCompletionQueue 함수에 전달된 RIO_NOTIFICATION_COMPLETION 구조체의 Event.NotifyReset 멤버는 RIONotify 함수 호출의 일부로 이벤트를 다시 설정해야 하는지 여부를 나타냅니다. 애플리케이션이 이벤트를 다시 설정하고 다시 사용하려는 경우 애플리케이션은 Event.NotifyReset 멤버를 0이 아닌 값으로 설정하여 오버헤드를 줄일 수 있습니다. 이렇게 하면 알림이 발생할 때 RIONotify 함수에 의해 이벤트가 자동으로 다시 설정됩니다. 이렇게 하면 RIONotify 함수 호출 간에 이벤트를 다시 설정하기 위해 WSAResetEvent 함수를 호출할 필요가 없습니다.

RIO_NOTIFICATION_COMPLETION 구조의 Type 멤버가 RIO_IOCP_COMPLETION 설정된 경우 I/O 완료 포트를 사용하여 완료 큐 알림을 보냅니다. I/O 완료 포트 핸들은 RIOCreateCompletionQueue 함수에 전달된 RIO_NOTIFICATION_COMPLETION 구조체에서 Iocp.IocpHandle 멤버로 제공됩니다. 이 RIO_CQ대한 RIONotify 함수가 완료되면 GetQueuedCompletionStatus 또는 GetQueuedCompletionStatusEx 함수를 사용하여 검색할 수 있는 I/O 완료 포트에 대한 항목이 큐에 대기합니다. 큐에 대기 중인 항목에는 반환된 lpCompletionKey 매개 변수 값이 RIO_NOTIFICATION_COMPLETION 구조체의 Iocp.CompletionKey 멤버에 지정된 값으로 설정되고 RIO_NOTIFICATION_COMPLETION 구조의 Iocp.Overlapped 멤버는 NULL이 아닌 값이 됩니다.

사용량 측면에서 완료 큐 알림은 스레드가 완료 큐를 검사할 수 있도록 대기 중인 애플리케이션 스레드를 해제하도록 설계되었습니다. 스레드를 깨우고 예약하는 데 비용이 들기 때문에 너무 자주 발생하는 경우 애플리케이션 성능에 부정적인 영향을 줍니다. 애플리케이션이 이러한 이벤트의 빈도를 제어하고 성능에 미치는 영향을 제한할 수 있도록 RIO_MSG_DONT_NOTIFY 플래그가 제공됩니다.

참고

효율성을 위해 완료 큐(RIO_CQ 구조체) 및 요청 큐(RIO_RQ 구조체)에 대한 액세스는 동기화 기본 형식으로 보호되지 않습니다. 여러 스레드에서 완료 또는 요청 큐에 액세스해야 하는 경우 중요한 섹션, 슬림 판독기 쓰기 잠금 또는 유사한 메커니즘을 통해 액세스를 조정해야 합니다. 이 잠금은 단일 스레드의 액세스에 필요하지 않습니다. 다른 스레드는 잠금 없이 별도의 요청/완료 큐에 액세스할 수 있습니다. 동기화의 필요성은 여러 스레드가 동일한 큐에 액세스하려고 할 때만 발생합니다. 송신 및 수신 작업이 소켓의 요청 큐를 사용하기 때문에 여러 스레드 문제가 동일한 소켓에서 보내고 받는 경우에도 동기화가 필요합니다.

 

참고

지정된 SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER opcode를 사용하여 WSAIoctl 함수를 호출하여 런타임에 RIOCreateCompletionQueue 함수에 대한 함수 포인터를 가져와야 합니다. WSAIoctl 함수에 전달된 입력 버퍼에는 값이 Winsock 등록 I/O 확장 함수를 식별하는 GUID(Globally Unique Identifier)인 WSAID_MULTIPLE_RIO 포함되어야 합니다. 성공하면 WSAIoctl 함수에서 반환된 출력에는 Winsock 등록 I/O 확장 함수에 대한 포인터가 포함된 RIO_EXTENSION_FUNCTION_TABLE 구조체에 대한 포인터가 포함됩니다. SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL은 Ws2def.h 헤더 파일에 정의되어 있습니다. WSAID_MULTIPLE_RIO GUID는 Mswsock.h 헤더 파일에 정의되어 있습니다.

 

Windows Phone 8: 이 함수는 Windows Phone 8 이상에서 Windows Phone 스토어 앱에서 지원됩니다.

Windows 8.1 및 Windows Server 2012 R2: 이 함수는 Windows 8.1, Windows Server 2012 R2 이상에서 Windows 스토어 앱에서 지원됩니다.

요구 사항

요구 사항 값
헤더 mswsock.h