Função CreateIoCompletionPort (ioapiset.h)
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.
A associação de uma instância de um identificador de arquivo aberto a uma porta de conclusão de E/S permite que um processo receba uma notificação da conclusão de operações de E/S assíncronas envolvendo esse identificador de arquivo.
O termo identificador de arquivo, conforme 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 sobrepostas, 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 CreateIoCompletionPort(
[in] HANDLE FileHandle,
[in, optional] HANDLE ExistingCompletionPort,
[in] ULONG_PTR CompletionKey,
[in] DWORD NumberOfConcurrentThreads
);
Parâmetros
[in] FileHandle
Um identificador de arquivo aberto ou INVALID_HANDLE_VALUE.
O identificador deve ser para um objeto que dá suporte à E/S sobreposta.
Se um identificador for fornecido, ele precisará 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.
[in, optional] ExistingCompletionPort
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 associará 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, o associará à nova porta de conclusão de E/S. Caso contrário, não ocorrerá nenhuma associação de identificador de arquivo. A função retornará o identificador para a nova porta de conclusão de E/S se tiver êxito.
[in] CompletionKey
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.
[in] NumberOfConcurrentThreads
O número máximo de threads que o sistema operacional pode permitir para 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á o mesmo número de threads em execução simultânea que há de processadores no sistema.
Valor retornado
Se a função for bem-sucedida, o valor retornado será o identificador para 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 for um identificador válido, esse identificador de arquivo agora está associado à porta de conclusão de E/S retornada.
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, onde eles são enfileirados. 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 é compartilhável entre os processos. No entanto, um único identificador é compartilhá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.
O identificador passado no parâmetro FileHandle pode ser qualquer identificador que dê suporte à E/S sobreposta. Normalmente, 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, confira 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 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 acompanhar 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 o acompanha durante todo o processo interno de enfileiramento de conclusão. 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 é associada a uma porta de conclusão de E/S, ela não pode 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 de identificador ou uma chamada para a função DuplicateHandle. As operações executadas com esses identificadores duplicados geram notificações de conclusão. É recomendável ter atenção especial.
O identificador de porta de conclusão de E/S e cada identificador de arquivo associado a essa porta de conclusão de E/S específica 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 de sistema associados. Depois que essas condições forem atendidas, feche o identificador de porta de conclusão de E/S chamando a função CloseHandle.
No Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.
| Tecnologia | Com suporte |
|---|---|
| Protocolo SMB (SMB) 3.0 | Sim |
| TFO (Failover transparente) do SMB 3.0 | Sim |
| SMB 3.0 com compartilhamentos de arquivos de expansão (SO) | Sim |
| Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS) | Sim |
| ReFS (Sistema de Arquivos Resiliente) | Sim |
Requisitos
| 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] |
| Plataforma de Destino | Windows |
| Cabeçalho | ioapiset.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Funções de gerenciamento de arquivos
Funções
Tópicos de visão geral