Função CreateIoCompletionPort

Cria uma porta de conclusão de E/S (entrada/saída) e a associa a um identificador de arquivo especificado ou cria uma porta de conclusão de E/S que ainda não está associada a um identificador de arquivo, permitindo a associação posteriormente.

Associar uma instância de um identificador de arquivo aberto a uma porta de conclusão de E/S permite que um processo receba notificação da conclusão de operações de E/S assíncronas envolvendo esse identificador de arquivo.

Observação

O identificador de arquivo de termo usado aqui refere-se a uma abstração do sistema que representa um ponto de extremidade de E/S sobreposto, não apenas um arquivo em disco. Todos os objetos do sistema que dão suporte a E/S sobrepostos, como pontos de extremidade de rede, soquetes TCP, pipes nomeados e slots de email podem ser usados como identificadores de arquivo. Para obter informações adicionais, consulte a seção Comentários.

Sintaxe

HANDLE WINAPI CreateIoCompletionPort(
  _In_     HANDLE    FileHandle,
  _In_opt_ HANDLE    ExistingCompletionPort,
  _In_     ULONG_PTR CompletionKey,
  _In_     DWORD     NumberOfConcurrentThreads
);

Parâmetros

FileHandle [in]

Um identificador de arquivo aberto ou INVALID_HANDLE_VALUE.

O identificador deve estar em um objeto que dê suporte a E/S sobreposta.

Se um identificador for fornecido, ele deverá ter sido aberto para conclusão de E/S sobreposta. Por exemplo, você deve especificar o sinalizador FILE_FLAG_OVERLAPPED ao usar a função CreateFile para obter o identificador.

Se INVALID_HANDLE_VALUE for especificado, a função criará uma porta de conclusão de E/S sem associá-la a um identificador de arquivo. Nesse caso, o parâmetro ExistingCompletionPort deve ser NULL e o parâmetro CompletionKey é ignorado.

ExistingCompletionPort [in, opcional]

Um identificador para uma porta de conclusão de E/S existente ou NULL.

Se esse parâmetro especificar uma porta de conclusão de E/S existente, a função a associa ao identificador especificado pelo parâmetro FileHandle . A função retornará o identificador da porta de conclusão de E/S existente se tiver êxito; ele não cria uma nova porta de conclusão de E/S.

Se esse parâmetro for NULL, a função criará uma nova porta de conclusão de E/S e, se o parâmetro FileHandle for válido, a associará à nova porta de conclusão de E/S. Caso contrário, nenhuma associação de identificador de arquivo ocorrerá. A função retorna o identificador para a nova porta de conclusão de E/S, se bem-sucedida.

CompletionKey [in]

A chave de conclusão definida pelo usuário por identificador incluída em cada pacote de conclusão de E/S para o identificador de arquivo especificado. Para obter mais informações, consulte a seção Comentários.

NumberOfConcurrentThreads [in]

O número máximo de threads que o sistema operacional pode permitir processar simultaneamente pacotes de conclusão de E/S para a porta de conclusão de E/S. Esse parâmetro será ignorado se o parâmetro ExistingCompletionPort não for NULL.

Se esse parâmetro for zero, o sistema permitirá tantos threads em execução simultânea quanto há processadores no sistema.

Valor retornado

Se a função for bem-sucedida, o valor retornado será o identificador de uma porta de conclusão de E/S:

  • Se o parâmetro ExistingCompletionPort for NULL, o valor retornado será um novo identificador.

  • Se o parâmetro ExistingCompletionPort for um identificador de porta de conclusão de E/S válido, o valor retornado será o mesmo identificador.

  • Se o parâmetro FileHandle era um identificador válido, esse identificador de arquivo agora está associado à porta de conclusão de E/S retornada.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame a função GetLastError .

Comentários

O sistema de E/S pode ser instruído a enviar pacotes de notificação de conclusão de E/S para portas de conclusão de E/S, em que eles estão na fila. A função CreateIoCompletionPort fornece essa funcionalidade.

Uma porta de conclusão de E/S e seu identificador estão associados ao processo que a criou e não é fragmentável entre os processos. No entanto, um único identificador é fragmentável entre threads no mesmo processo.

CreateIoCompletionPort pode ser usado em três modos distintos:

  • Crie apenas uma porta de conclusão de E/S sem associá-la a um identificador de arquivo.
  • Associe uma porta de conclusão de E/S existente a um identificador de arquivo.
  • Execute a criação e a associação em uma única chamada.

Para criar uma porta de conclusão de E/S sem associá-la, defina o parâmetro FileHandle como INVALID_HANDLE_VALUE, o parâmetro ExistingCompletionPort como NULL e o parâmetro CompletionKey como zero (o que é ignorado nesse caso). Defina o parâmetro NumberOfConcurrentThreads como o valor de simultaneidade desejado para a nova porta de conclusão de E/S ou zero para o padrão (o número de processadores no sistema).

O identificador passado no parâmetro FileHandle pode ser qualquer identificador que dê suporte a E/S sobreposta. Mais comumente, esse é um identificador aberto pela função CreateFile usando o sinalizador FILE_FLAG_OVERLAPPED (por exemplo, arquivos, slots de email e pipes). Objetos criados por outras funções, como soquete , também podem ser associados a uma porta de conclusão de E/S. Para obter um exemplo usando soquetes, consulte AcceptEx. Um identificador pode ser associado a apenas uma porta de conclusão de E/S e, depois que a associação for feita, o identificador permanecerá associado a essa porta de conclusão de E/S até que ela seja fechada.

Para obter mais informações sobre a teoria da porta de conclusão de E/S, o uso e as funções associadas, consulte Portas de Conclusão de E/S.

Vários identificadores de arquivo podem ser associados a uma única porta de conclusão de E/S chamando CreateIoCompletionPort várias vezes com o mesmo identificador de porta de conclusão de E/S no parâmetro ExistingCompletionPort e um identificador de arquivo diferente no parâmetro FileHandle cada vez.

Use o parâmetro CompletionKey para ajudar seu aplicativo a controlar quais operações de E/S foram concluídas. Esse valor não é usado por CreateIoCompletionPort para controle funcional; em vez disso, ele é anexado ao identificador de arquivo especificado no parâmetro FileHandle no momento da associação com uma porta de conclusão de E/S. Essa chave de conclusão deve ser exclusiva para cada identificador de arquivo e acompanha o identificador de arquivo durante todo o processo de enfileiramento de conclusão interno. Ele é retornado na chamada da função GetQueuedCompletionStatus quando um pacote de conclusão chega. O parâmetro CompletionKey também é usado pela função PostQueuedCompletionStatus para enfileirar seus próprios pacotes de conclusão de finalidade especial.

Depois que uma instância de um identificador aberto estiver associada a uma porta de conclusão de E/S, ela não poderá ser usada na função ReadFileEx ou WriteFileEx porque essas funções têm seus próprios mecanismos de E/S assíncronos.

É melhor não compartilhar um identificador de arquivo associado a uma porta de conclusão de E/S usando a herança do identificador ou uma chamada para a função DuplicateHandle . Operações executadas com essas alças duplicadas geram notificações de conclusão. Consideração cuidadosa é aconselhável.

O identificador da porta de conclusão de E/S e cada identificador de arquivo associado a essa porta de conclusão de E/S em particular são conhecidos como referências à porta de conclusão de E/S. A porta de conclusão de E/S é liberada quando não há mais referências a ela. Portanto, todos esses identificadores devem ser devidamente fechados para liberar a porta de conclusão de E/S e seus recursos do sistema associados. Depois que essas condições forem atendidas, feche o identificador da porta de conclusão de E/S chamando a função CloseHandle .

Em Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia Com suporte
Protocolo SMB (Bloco de Mensagens do Servidor) 3.0
Sim
TFO (Failover Transparente) SMB 3.0
Sim
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)
Sim
Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS)
Sim
ReFS (Sistema de Arquivos Resiliente)
Sim

Requisitos

Requisito Valor
Cliente mínimo com suporte
Windows XP [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte
Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Cabeçalho
IoAPI.h (include Windows.h);
WinBase.h no Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP (inclua Windows.h)
Biblioteca
Kernel32.lib
DLL
Kernel32.dll

Confira também

Tópicos de visão geral

Funções de gerenciamento de arquivos

Portas de conclusão de E/S

Usando os cabeçalhos Windows

soquetes Windows 2

Funções

AcceptEx

CreateFile

Duplicatehandle

GetQueuedCompletionStatus

GetQueuedCompletionStatusEx

PostQueuedCompletionStatus

ReadFileEx

WriteFileEx