LPFN_RIOCREATECOMPLETIONQUEUE función de devolución de llamada (mswsock.h)
La función RIOCreateCompletionQueue crea una cola de finalización de E/S de un tamaño específico para su uso con las extensiones de E/S registradas de Winsock.
Sintaxis
LPFN_RIOCREATECOMPLETIONQUEUE LpfnRiocreatecompletionqueue;
RIO_CQ LpfnRiocreatecompletionqueue(
DWORD QueueSize,
PRIO_NOTIFICATION_COMPLETION NotificationCompletion
)
{...}
Parámetros
QueueSize
Tamaño, en número de entradas, de la cola de finalización que se va a crear.
NotificationCompletion
Tipo de finalización de notificación que se va a usar en función del miembro Type de la estructura de RIO_NOTIFICATION_COMPLETION (finalización de E/S o notificación de eventos).
Si el miembro Type se establece en RIO_EVENT_COMPLETION, se debe establecer el miembro Event de la estructura RIO_NOTIFICATION_COMPLETION .
Si el miembro Type se establece en RIO_IOCP_COMPLETION, el miembro Iocp de la estructura RIO_NOTIFICATION_COMPLETION debe establecerse y el miembro Iocp.Superpuesto de la estructura RIO_NOTIFICATION_COMPLETION no debe ser NULL.
Si el parámetro NotificationCompletion es NULL, esto especifica que no se use ninguna finalización de notificación y que el sondeo se debe usar para determinar la finalización.
Valor devuelto
Si no se produce ningún error, la función RIOCreateCompletionQueue devuelve un descriptor que hace referencia a una nueva cola de finalización. De lo contrario, se devuelve un valor de RIO_INVALID_CQ y se puede recuperar un código de error específico llamando a la función WSAGetLastError .
| Código devuelto | Descripción |
|---|---|
| El sistema ha detectado una dirección de puntero no válida al intentar usar un argumento de puntero en una llamada. |
|
| Se pasó un parámetro no válido a la función. Este error se devuelve si el parámetro QueueSize es menor que 1 o mayor que RIO_MAX_CQ_SIZE definido en el archivo de encabezado Mswsockdef.h . |
|
| No se pudo asignar memoria suficiente. Este error se devuelve si no había memoria suficiente para asignar la cola de finalización solicitada en función del parámetro QueueSize . |
Comentarios
La función RIOCreateCompletionQueue crea una cola de finalización de E/S de un tamaño específico. El tamaño de la cola de finalización restringe el conjunto de sockets de E/S registrados que se pueden asociar a la cola de finalización. Para obtener más información, consulte la función RIOCreateRequestQueue .
Al crear un RIO_CQ, la estructura de RIO_NOTIFICATION_COMPLETION a la que apunta el parámetro NotificationCompletion determina cómo la aplicación recibirá notificaciones de cola de finalización. Si se proporciona una estructura de RIO_NOTIFICATION_COMPLETION al crear la cola de finalización, la aplicación puede llamar a la función RIONotify para solicitar una notificación de cola de finalización. Normalmente, esta notificación se produce cuando la cola de finalización no está vacía. Esto puede ocurrir inmediatamente o cuando se inserta la siguiente entrada de finalización en la cola de finalización. Sin embargo, las solicitudes de envío y recepción se pueden marcar como RIO_MSG_DONT_NOTIFY. Notificación de cola de finalización y nunca se desencadenará como resultado de dichas solicitudes. Si la cola de finalización solo contiene entradas con la marca RIO_MSG_DONT_NOTIFY establecida, no se desencadenará la notificación de cola de finalización. Además, cuando una nueva entrada entra en la cola de finalización, la notificación de cola de finalización solo se desencadena si la marca RIO_MSG_DONT_NOTIFY no se estableció en la solicitud asociada. Las solicitudes completadas todavía se pueden recuperar mediante el sondeo mediante la función RIODequeueCompletion . Una vez que se emite una notificación de cola de finalización, la aplicación debe llamar a la función RIONotify para recibir otra notificación de cola de finalización. Cuando se produce una notificación de cola de finalización, la aplicación normalmente llama a la función RIODequeueCompletion para poner en cola las solicitudes de envío o recepción completadas.
Hay dos opciones disponibles para la notificación de cola de finalización.
- Identificadores de eventos.
- Puertos de finalización de E/S
Si el miembro Type de la estructura RIO_NOTIFICATION_COMPLETION se establece en RIO_EVENT_COMPLETION, se usa un identificador de eventos para indicar las notificaciones de cola de finalización. Se proporciona un identificador de evento como miembro EventNotify.EventHandle en la estructura de RIO_NOTIFICATION_COMPLETION pasada a la función RIOCreateCompletionQueue . El miembro Event.EventHandle debe contener el identificador de un evento creado por la función WSACreateEvent o CreateEvent . Para recibir la finalización de RIONotify , la aplicación debe esperar en el identificador de eventos especificado mediante WSAWaitForMultipleEvents o una rutina de espera similar. La finalización de la función RIONotify para este RIO_CQ indicará el evento. El miembro Event.NotifyReset de la estructura RIO_NOTIFICATION_COMPLETION pasada a la función RIOCreateCompletionQueue indica si el evento debe restablecerse como parte de una llamada a la función RIONotify . Si la aplicación planea restablecer y reutilizar el evento, la aplicación puede reducir la sobrecarga estableciendo el miembro Event.NotifyReset en un valor distinto de cero. Esto hace que la función RIONotify restablezca automáticamente el evento cuando se produzca la notificación. Esto mitiga la necesidad de llamar a la función WSAResetEvent para restablecer el evento entre las llamadas a la función RIONotify .
Si el miembro Type de la estructura de RIO_NOTIFICATION_COMPLETION se establece en RIO_IOCP_COMPLETION, se usa un puerto de finalización de E/S para indicar las notificaciones de la cola de finalización. Se proporciona un identificador de puerto de finalización de E/S como miembro Iocp.IocpHandle en la estructura de RIO_NOTIFICATION_COMPLETION pasada a la función RIOCreateCompletionQueue . La finalización de la función RIONotify para este RIO_CQ pondrá en cola una entrada al puerto de finalización de E/S que se puede recuperar mediante la función GetQueuedCompletionStatus o GetQueuedCompletionStatusEx . Una entrada en cola tendrá el valor de parámetro lpCompletionKey devuelto establecido en el valor especificado en el miembro Iocp.CompletionKey de la estructura RIO_NOTIFICATION_COMPLETION y el miembro Iocp.Superpuesto en la estructura RIO_NOTIFICATION_COMPLETION será un valor distinto de NULL.
En términos de su uso, la notificación de cola de finalización está diseñada para reactivar un subproceso de aplicación en espera para que el subproceso pueda examinar la cola de finalización. Despertar y programar un subproceso conlleva un costo, por lo que si esto sucede con demasiada frecuencia, tendrá un impacto negativo en el rendimiento de la aplicación. La marca RIO_MSG_DONT_NOTIFY se proporciona para que la aplicación pueda controlar la frecuencia de estos eventos y limitar su impacto sobre el rendimiento.
Nota
Con fines de eficacia, el acceso a las colas de finalización (RIO_CQ estructuras) y las colas de solicitudes (RIO_RQ estructuras) no están protegidos por primitivos de sincronización. Si necesita acceder a una cola de finalización o solicitud desde varios subprocesos, el acceso debe coordinarse mediante una sección crítica, un bloqueo de escritura de lector delgado o un mecanismo similar. Este bloqueo no es necesario para el acceso mediante un único subproceso. Diferentes subprocesos pueden acceder a solicitudes o colas de finalización independientes sin bloqueos. La necesidad de sincronización solo se produce cuando varios subprocesos intentan acceder a la misma cola. La sincronización también es necesaria si varios subprocesos se envían y reciben en el mismo socket porque las operaciones de envío y recepción usan la cola de solicitudes del socket.
Nota
El puntero de función a la función RIOCreateCompletionQueue se debe obtener en tiempo de ejecución realizando una llamada a la función WSAIoctl con el código de operación SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER especificado. El búfer de entrada pasado a la función WSAIoctl debe contener WSAID_MULTIPLE_RIO, un identificador único global (GUID) cuyo valor identifica las funciones de extensión de E/S registradas de Winsock. Si se ejecuta correctamente, la salida devuela por la función WSAIoctl contiene un puntero a la estructura de RIO_EXTENSION_FUNCTION_TABLE que contiene punteros a las funciones de extensión de E/S registradas de Winsock. El SIO_GET_MULTIPLE_EXTENSION_FUNCTION_POINTER IOCTL se define en el archivo de encabezado Ws2def.h . El GUID de WSAID_MULTIPLE_RIO se define en el archivo de encabezado Mswsock.h .
Windows Phone 8: esta función es compatible con las aplicaciones de Windows Phone Store en Windows Phone 8 y versiones posteriores.
Windows 8.1 y Windows Server 2012 R2: esta función es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.
Requisitos
| Requisito | Valor |
|---|---|
| Header | mswsock.h |
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de