Subrotina GetMultipleCompletionStatus

Editar online

Propósito

Desfila vários pacotes de conclusão de um porta de conclusão de E/S especificado.

Sintaxe

#include <sys/iocp.h>
int GetMultipleCompletionStatus (CompletionPort, Nmin, Nmax, Timeout, Results[])
HANDLE CompletionPort;
DWORD Nmin, Nmax, Timeout;
struct gmcs {
    DWORD transfer_count, completion_key, errorno;
    LPOVERLAPPED overlapped;
} Results[];

Descrição

O sub-rotina GetMultipleCompletionStatus tenta retirar da fila um número de pacotes de conclusão da porta de conclusão especificada pelo parâmetro CompletionPort. O número de pacotes de conclusão desfileirados que são desejados varia do valor do parâmetro Nmin através do valor do parâmetro Nmax . À medida que coleta os pacotes, este subroutine pode esperar uma quantidade máxima predeterminada de tempo que é especificado pelo parâmetro Timeout para o número mínimo de pacotes de conclusão a chegar. Se, por exemplo, o Xº pacote de conclusão não chegar a tempo, a sub-rotina retornará com apenas X-1 pacotes concluídos.

Ou o parâmetro Timeout ou um sinal pode causar um retorno com compleções a menos do que o valor do parâmetro Nmin . Em outras palavras, a complementação do Nmin não é garantida para ser devolvida, a menos que o valor do parâmetro Timeout seja configurado como INFINITE, e um sinal não interrompa a espera. O retorno de complementos zero não é considerado um erro. O valor errno irá, no entanto, indicar a condição com o código de erro ETIMEDOUT ou EINTR . Em situações extremas de baixa memória, o kernel pode não ser capaz de fornecer um tempo limite. Neste caso, a chamada do sistema retorna imediatamente com qualquer complementação disponível, até o valor do parâmetro Nmax , e o valor errno é configurado como ENOMEM. Certifique-se de definir o valor errno como zero antes de chamar o subprograma GetMultipleCompletionStatus para que a alteração do valor errno feita pelo subprograma possa ser diferenciada do valor existente.

A sub-rotina GetMultipleCompletionStatus faz parte da extensão do kernel da porta de conclusão de E/S (IOCP).

Observação:
  1. Esta subroutine só funciona com descritores de arquivos de soquetes, ou arquivos regulares para uso com o subsistema de E/S assíncrono. Ele não funciona com descritores de arquivo de outros tipos.
  2. Esta função deve ser o mecanismo de espera exclusivo em uma porta de conclusão. Não há suporte para várias esperas simultâneas por meio da sub-rotina GetMultipleCompletionStatus, da sub-rotina GetQueuedCompletionStatus ou de ambas.
  3. Quando a sub-rotina GetMultipleCompletionStatus é usada com a sub-rotina lio_listio, você pode definir o valor do parâmetro cmd da sub-rotina lio_listio como LIO_NOWAIT_GMCS para evitar a atualização assíncrona das estruturas aiocb, reduzindo assim a sobrecarga. Nesse caso, você deve usar a sub-rotina GetMultipleCompletionStatus para aguardar as conclusões de E/S e recuperar o status de conclusão somente dos membros da estrutura gmcs, não da estrutura aiocb. Ao usar o valor LIO_NOWAIT_GMCS , não use o valor completion_key na estrutura gmcs . Não use o valor LIO_NOWAIT_AIOWAIT com a sub-rotina lio_listio ao usar a sub-rotina GetMultipleCompletionStatus. O valor LIO_NOWAIT_GMCS está disponível para essa finalidade.
  4. O cancelamento de uma operação de E/S assíncrona não afetará o subprograma GetMultipleCompletionStatus. Mesmo que o cancelamento reduza o número de operações de E/S assíncronas ativas para zero, a subroutine continuará a aguardar.
  5. Ao usar a sub-rotina GetMultipleCompletionStatus com soquetes, não espere por várias conclusões(Nmin > 1) com um tempo limite INFINITO. Use um valor de tempo limite finito, e para estar preparado para repetir a chamada se complementos adicionais ainda são esperados.

Parâmetros

Item Descrição Atributo Descrição
CompletionPort Especifica o descritor de arquivo para a porta de conclusão que esta subroutine irá acessar.  
Nmin Especifica o número mínimo de complementos. Menos pode ser retornado se o valor do parâmetro timeout for excedido, ou um sinal aceito. Mais pode ser retornado, até o número que é especificado pelo parâmetro Nmax , caso ocorram complementos adicionais. Configurar o valor do parâmetro Nmin para zero irá pesquisar por compleções e retornar imediatamente, ignorando o valor do parâmetro timeout .  
Nmax Especifica o número máximo de complementos à espera, até o valor da macro GMCS_NMAX.  
Resultados Este é o endereço de uma matriz da estrutura do gmcs para receber os dados de conclusão. A matriz deve conter espaço para o número de entradas especificado pelo parâmetro Nmax .  
  Resultados [i]. contagem de transferência Especifica o número de bytes transferidos. Este parâmetro é configurado pela subroutine a partir do valor recebido no pacote de conclusão ith . Este valor é limitado a 2 G.
  Resultados [i] .completion_key Especifica a chave de conclusão associada ao descritor de arquivo que é utilizado na solicitação de transferência. Este parâmetro é configurado pela subroutine a partir do valor recebido no pacote de conclusão ith . Não use este valor com o parâmetro de comando LIO_NOWAIT_GMCS da subroutina lio_listio .
  Resultados [i] .errorno Especifica o valor errno que está associado ao pacote de conclusão de conclusão ith . Quando as solicitações de E/S assíncronas são iniciadas usando a subroutine lio_listio com o parâmetro de comando LIO_NOWAIT_GMCS , você deve usar este valor de erro, não o membro aio_errno na estrutura aiocb , para recuperar o valor de erro que está associado a uma solicitação de E/S.
  Resultados [i] .sobrepostos Especifica a estrutura sobreposta que é utilizada no pedido de transferência. Este parâmetro é configurado pela subroutine a partir do valor recebido no pacote de conclusão ith . Para arquivos regulares, este parâmetro contém um ponteiro para o bloco de controle de E/S assíncrono (AIOCB) para uma solicitação AIO concluída. Se um aplicativo usa a mesma porta de conclusão para ambos os socket e AIO para arquivos regulares, ele deve usar valores exclusivos completion_key para diferenciar entre sockets e arquivos regulares para interpretar adequadamente o parâmetro overlapped .
Tempo limite Especifica a quantidade de tempo em milissegundos que a subroutine é para aguardar pacotes de conclusão. Esse valor pode ser definido como zero. Se este parâmetro for configurado para INFINITE, a subroutine nunca irá tempo fora.  

Valores De Retorno

Item Descrição
Sucesso A subroutine retorna um número inteiro que varia de zero por meio do valor do parâmetro Nmax , indicando quantos pacotes de conclusão são desfileirados.
Falha A sub-rotina retorna um valor de -1.

Códigos de erro

A subroutine não é bem sucedida se ocorrer algum dos seguintes erros:

Item Descrição
EINVAL O valor de CompletionPort ou outro parâmetro não é válido.
EBUSY Outro encadeamento já está aguardando no porta de conclusão de I/O.
EBADF Esse código de erro também pode ser retornado quando o valor do parâmetro CompletionPort não for válido.

Se ocorrer um erro após algumas compleções terem sido manipuladas, as notificações de erro serão perdidas. Um erro EFAULT ao copiar resultados pode causar a situação.

Exemplos

  1. O fragmento de programa a seguir ilustra o uso da sub-rotina GetMultipleCompletionStatus para retirar da fila até 10 pacotes de conclusão em uma janela de 100 milissegundos.
    struct gmcs results[10];
int n_results;
HANDLE iocpfd;
errno = 0;
n_results = GetMultipleCompletionStatus(iocpfd, 10, 10, 100, results);