RIO_CQ
O typedef RIO_CQ especifica um descritor de fila de conclusão usado para notificação de conclusão de E/S enviando e recebendo solicitações com as extensões de E/S registradas do Winsock.
typedef struct RIO_CQ_t* RIO_CQ, **PRIO_CQ;
-
RIO_CQ
-
Um tipo de dados que especifica um descritor de fila de conclusão usado para notificação de conclusão de E/S enviando e recebendo solicitações.
O objeto RIO_CQ é usado para notificação de conclusão de E/S de enviar e receber solicitações de rede pelas extensões de E/S registradas do Winsock.
Um aplicativo pode usar a função RIONotify para solicitar notificação quando uma fila de conclusão de RIO_CQ não estiver vazia. Um aplicativo também pode sondar o status a qualquer momento de uma fila de conclusão RIO_CQ de forma não bloqueada usando a função RIODequeueCompletion.
O objeto RIO_CQ é criado usando a função RIOCreateCompletionQueue . No momento da criação, o aplicativo deve especificar o tamanho da fila, que determina quantas entradas de conclusão ele pode conter. Quando um aplicativo chama a função RIOCreateRequestQueue para obter um identificador de RIO_RQ , o aplicativo deve especificar um identificador de RIO_CQ para conclusões de envio e um identificador de RIO_CQ para conclusões de recebimento. Esses identificadores podem ser idênticos quando a mesma fila deve ser usada para enviar e receber a conclusão. A função RIOCreateRequestQueue também requer um número máximo de operações pendentes de envio e recebimento, que são cobradas em relação à capacidade da fila ou filas de conclusão associadas. Se as filas não tiverem capacidade suficiente restante, a chamada RIOCreateRequestQueue falhará com WSAENOBUFS.
O comportamento de notificação de uma fila de conclusão é definido quando o RIO_CQ é criado.
Para uma fila de conclusão que usa um evento, o membro Type da estrutura RIO_NOTIFICATION_COMPLETION é definido como RIO_EVENT_COMPLETION. O membro Event.EventHandle deve conter o identificador de um evento criado pela função WSACreateEvent ou CreateEvent . Para receber a conclusão do RIONotify , o aplicativo deve aguardar o identificador de evento especificado usando WSAWaitForMultipleEvents ou uma rotina de espera semelhante. Se o aplicativo planeja redefinir e reutilizar o evento, o aplicativo poderá reduzir a sobrecarga definindo o membro Event.NotifyReset como um valor diferente de zero. Isso faz com que o evento seja redefinido automaticamente pela função RIONotify quando a notificação ocorre. Isso atenua a necessidade de chamar a função WSAResetEvent para redefinir o evento entre chamadas para a função RIONotify .
Para uma fila de conclusão que usa uma porta de conclusão de E/S, o membro Type da estrutura RIO_NOTIFICATION_COMPLETION é definido como RIO_IOCP_COMPLETION. O membro Iocp.IocpHandle deve conter o identificador de uma porta de conclusão de E/S criada pela função CreateIoCompletionPort . Para receber a conclusão do RIONotify , o aplicativo deve chamar a função GetQueuedCompletionStatus ou GetQueuedCompletionStatusEx . O aplicativo deve fornecer um objeto OVERLAPPED dedicado para a fila de conclusão e também pode usar o membro Iocp.CompletionKey para distinguir as solicitações RIONotify na fila de conclusão de outras conclusões de E/S, incluindo CONCLUSÕES RIONotify para outras filas de conclusão.
Observação
Para fins de eficiência, o acesso às filas de conclusão (RIO_CQ structs) e às filas de solicitação (RIO_RQ structs) não são protegidos por primitivos de sincronização. Se você precisar acessar uma fila de conclusão ou solicitação de vários threads, o acesso deverá ser coordenado por uma seção crítica, bloqueio de gravação de leitor fino ou mecanismo semelhante. Esse bloqueio não é necessário para acesso por um único thread. Threads diferentes podem acessar filas de solicitações/conclusão separadas sem bloqueios. A necessidade de sincronização ocorre somente quando vários threads tentam acessar a mesma fila. A sincronização também será necessária se vários threads forem enviados e recebidos no mesmo soquete porque as operações de envio e recebimento usarão a fila de solicitação do soquete.
Se vários threads tentarem acessar o mesmo RIO_CQ usando RIODequeueCompletion, o acesso deverá ser coordenado por uma seção crítica, bloqueio de gravador de leitor fino ou mecanismo de exclusão mútua semelhante. Se as filas de conclusão não forem compartilhadas, a exclusão mútua não será necessária.
Quando uma fila de conclusão não é mais necessária, um aplicativo pode fechá-la usando a função RIOCloseCompletionQueue .
O typedef RIO_CQ é definido no arquivo de cabeçalho Mswsockdef.h que é incluído automaticamente no arquivo de cabeçalho Mswsock.h . O arquivo de cabeçalho Mswsockdef.h nunca deve ser usado diretamente.
Se vários threads tentarem acessar o mesmo RIO_CQ usando RIODequeueCompletion, o acesso deverá ser coordenado por uma seção crítica, bloqueio de gravador de leitor fino ou mecanismo de exclusão mútua semelhante. Se as filas de conclusão não forem compartilhadas, a exclusão mútua não será necessária.
Requisito | Valor |
---|---|
Cliente mínimo com suporte |
Windows 8 [somente aplicativos da área de trabalho] |
Servidor mínimo com suporte |
Windows Server 2012 [somente aplicativos da área de trabalho] |
Cabeçalho |
|