функция обратного вызова LPFN_RIOCREATECOMPLETIONQUEUE (mswsock.h)

Функция RIOCreateCompletionQueue создает очередь завершения ввода-вывода определенного размера для использования с зарегистрированными расширениями ввода-вывода Winsock.

Синтаксис

LPFN_RIOCREATECOMPLETIONQUEUE LpfnRiocreatecompletionqueue;

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

Параметры

QueueSize

Размер создаваемой очереди завершения в количестве записей.

NotificationCompletion

Тип завершения уведомления для использования на основе элемента Typeструктуры RIO_NOTIFICATION_COMPLETION (завершение ввода-вывода или уведомление о событии).

Если для элемента Type задано значение RIO_EVENT_COMPLETION, необходимо задать элемент Eventструктуры RIO_NOTIFICATION_COMPLETION .

Если для элемента Type задано значение RIO_IOCP_COMPLETION, то необходимо задать элемент Iocpструктуры RIO_NOTIFICATION_COMPLETION , а элемент Iocp.Overlapped структуры RIO_NOTIFICATION_COMPLETION не должен иметь значение NULL.

Если параметр NotificationCompletion имеет значение NULL, это означает, что завершение уведомления не используется, и для определения завершения необходимо использовать опрос.

Возвращаемое значение

Если ошибка не возникает, функция RIOCreateCompletionQueue возвращает дескриптор, ссылающийся на новую очередь завершения. В противном случае возвращается значение RIO_INVALID_CQ , а конкретный код ошибки можно получить, вызвав функцию WSAGetLastError .

Комментарии

Функция RIOCreateCompletionQueue создает очередь завершения ввода-вывода определенного размера. Размер очереди завершения ограничивает набор зарегистрированных сокетов ввода-вывода, которые могут быть связаны с очередью завершения. Дополнительные сведения см. в разделе Функция RIOCreateRequestQueue .

При создании RIO_CQ структура RIO_NOTIFICATION_COMPLETION , на которую указывает параметр NotificationCompletion , определяет, как приложение будет получать уведомления очереди завершения. Если при создании очереди завершения предоставляется структура RIO_NOTIFICATION_COMPLETION , приложение может вызвать функцию RIONotify для запроса уведомления очереди завершения. Обычно это уведомление возникает, если очередь завершения не пуста. Это может произойти немедленно или при вставке следующей записи завершения в очередь завершения. Однако запросы на отправку и получение могут быть помечены как RIO_MSG_DONT_NOTIFY. Уведомление о завершении очереди и никогда не будет активировано в результате таких запросов. Если очередь завершения содержит только записи с установленным флагом RIO_MSG_DONT_NOTIFY , уведомление очереди завершения не будет активировано. Кроме того, когда новая запись входит в очередь завершения, уведомление очереди завершения активируется только в том случае, если флаг RIO_MSG_DONT_NOTIFY не был установлен в связанном запросе. Все завершенные запросы по-прежнему можно получить путем опроса с помощью функции RIODequeueCompletion . После выдачи уведомления очереди завершения приложение должно вызвать функцию RIONotify , чтобы получить еще одно уведомление очереди завершения. При появлении уведомления очереди завершения приложение обычно вызывает функцию RIODequeueCompletion , чтобы вывести из очереди завершенные запросы отправки или получения.

Для уведомления о завершении очереди доступны два варианта.

• Дескрипторы событий.
• Порты завершения ввода-вывода

Если для элемента Type структуры RIO_NOTIFICATION_COMPLETION задано значение RIO_EVENT_COMPLETION, для уведомления очереди завершения используется дескриптор события. Дескриптор события предоставляется в качестве элемента EventNotify.EventHandle в структуре RIO_NOTIFICATION_COMPLETION , передаваемой функции RIOCreateCompletionQueue . Элемент Event.EventHandle должен содержать дескриптор события, созданного функцией WSACreateEvent или CreateEvent . Чтобы получить завершение RIONotify , приложение должно дождаться указанного дескриптора события с помощью WSAWaitForMultipleEvents или аналогичной процедуры ожидания. Завершение функции RIONotify для этого RIO_CQ будет сигнализировать о событии. Элемент Event.NotifyReset в структуре RIO_NOTIFICATION_COMPLETION , переданной функции RIOCreateCompletionQueue , указывает, следует ли сбросить событие в рамках вызова функции RIONotify . Если приложение планирует сбросить и повторно использовать событие, приложение может снизить затраты, задав для элемента Event.NotifyReset ненулевое значение. Это приводит к автоматическому сбросу события функцией RIONotify при возникновении уведомления. Это устраняет необходимость вызова функции WSAResetEvent для сброса события между вызовами функции RIONotify .

Если для элемента Type структуры RIO_NOTIFICATION_COMPLETION задано значение RIO_IOCP_COMPLETION, порт завершения ввода-вывода используется для передачи уведомлений очереди завершения. Дескриптор порта завершения ввода-вывода предоставляется в качестве члена Iocp.IocpHandle в структуре RIO_NOTIFICATION_COMPLETION , передаваемой в функцию RIOCreateCompletionQueue . Завершение функции RIONotify для этого RIO_CQ помещает запись в очередь на порт завершения ввода-вывода, который можно получить с помощью функции GetQueuedCompletionStatus или GetQueuedCompletionStatusEx . Запись в очереди будет иметь возвращаемое значение параметра lpCompletionKey , равное значению, указанному в элементе Iocp.CompletionKey структуры RIO_NOTIFICATION_COMPLETION , а элемент Iocp.Overlapped в структуре RIO_NOTIFICATION_COMPLETION будет иметь значение, отличное от NULL.

С точки зрения использования уведомление очереди завершения предназначено для пробуждения ожидающего потока приложения, чтобы поток смог проверить очередь завершения. Пробуждение и планирование потока обходится дорого, поэтому если это происходит слишком часто, это негативно скажется на производительности приложения. Флаг RIO_MSG_DONT_NOTIFY предоставляется для того, чтобы приложение я х 2000 года 2019 г. 2019 г.

Windows Phone 8. Эта функция поддерживается для приложений Магазина Windows Phone на Windows Phone 8 и более поздних версиях.

Windows 8.1 и Windows Server 2012 R2. Эта функция поддерживается для приложений Магазина Windows на Windows 8.1, Windows Server 2012 R2 и более поздних версиях.

Требования