CreateIoCompletionPort, fonction (ioapiset.h)

Article
08/24/2023

Crée un port d’achèvement d’entrée/sortie (E/S) et l’associe à un gestionnaire de fichiers spécifié, ou crée un port d’achèvement d’E/S qui n’est pas encore associé à un gestionnaire de fichiers, ce qui permettra de l’associer ultérieurement.

L’association d’une instance d’un descripteur de fichier ouvert à un port d’achèvement d’E/S permet à un processus de recevoir une notification de l’achèvement des opérations d’E/S asynchrones impliquant ce descripteur de fichier.

Remarque

Le terme descripteur de fichier, tel qu’il est utilisé ici, fait référence à une abstraction du système qui représente un point de terminaison d’E/S superposé, et pas seulement un fichier sur le disque. Tous les objets système qui prennent en charge les E/S qui se chevauchent, tels que les points de terminaison réseau, les sockets TCP, les canaux nommés et les emplacements de messagerie, peuvent être utilisés comme descripteurs de fichiers. Pour plus d’informations, consultez la section Remarques.

Syntaxe

HANDLE CreateIoCompletionPort(
  [in]           HANDLE    FileHandle,
  [in, optional] HANDLE    ExistingCompletionPort,
  [in]           ULONG_PTR CompletionKey,
  [in]           DWORD     NumberOfConcurrentThreads
);

Paramètres

[in] FileHandle

Un descripteur de fichier ouvert ou INVALID_HANDLE_VALUE.

Le descripteur doit correspondre à un objet qui prend en charge les E/S qui se chevauchent.

Si un descripteur est fourni, il doit avoir été ouvert pour que les E/S se chevauchent. Par exemple, vous devez spécifier l’indicateur FILE_FLAG_OVERLAPPED lors de l’utilisation de la fonction CreateFile pour obtenir le descripteur.

Si INVALID_HANDLE_VALUE est spécifié, la fonction crée un port d’achèvement d’E/S sans l’associer à un descripteur de fichier. Dans ce cas, le paramètre ExistingCompletionPort doit être NULL et le paramètre CompletionKey est ignoré.

[in, optional] ExistingCompletionPort

Un descripteur vers un port d’achèvement d’E/S existant ou NULL.

Si ce paramètre spécifie un port d’achèvement d’E/S existant, la fonction l’associe au descripteur spécifié par le paramètre FileHandle. En cas de succès, la fonction renvoie le descripteur du port d’achèvement d’E/S existant ; elle ne crée pas de nouveau port d’achèvement d’E/S.

Si ce paramètre est NULL, la fonction crée un nouveau port d’achèvement d’E/S, et si le paramètre FileHandle est valide, l’associe au nouveau port d’achèvement d’E/S. Dans le cas contraire, il n’y a pas d’association de descripteur de fichier. En cas de succès, la fonction renvoie le descripteur du nouveau port d’achèvement des E/S.

[in] CompletionKey

Clé d’achèvement définie par l’utilisateur pour chaque descripteur et incluse dans chaque paquet d’achèvement d’E/S pour le descripteur de fichier spécifié. Pour plus d'informations, consultez la section Notes.

[in] NumberOfConcurrentThreads

Nombre maximal de threads que le système d’exploitation peut autoriser à traiter simultanément les paquets d’achèvement d’E/S pour le port d’achèvement d’E/S. Ce paramètre est ignoré si le paramètre ExistingCompletionPort n’est pas NULL.

Si ce paramètre est égal à zéro, le système autorise l’exécution simultanée d’autant de threads qu’il y a de processeurs dans le système.

Valeur retournée

Si la fonction réussit, la valeur de retour est le descripteur d’un port d’achèvement d’E/S :

Si le paramètre ExistingCompletionPort était NULL, la valeur de retour est un nouveau descripteur.
Si le paramètre ExistingCompletionPort était un descripteur de port d’achèvement d’E/S valide, la valeur de retour est ce même descripteur.
Si le paramètre FileHandle était un descripteur valide, ce descripteur de fichier est maintenant associé au port d’achèvement d’E/S renvoyé.

Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez la fonction GetLastError.

Notes

Le système d’E/S peut être chargé d’envoyer des paquets de notification d’achèvement d’E/S aux ports d’achèvement d’E/S, où ils sont mis en file d’attente. La fonction CreateIoCompletionPort fournit cette fonctionnalité.

Un port d’achèvement d’E/S et son descripteur sont associés au processus qui l’a créé et ne sont pas partageables entre les processus. Toutefois, un descripteur unique peut être partagé entre les différents threads d’un même processus.

CreateIoCompletionPort peut être utilisé dans trois modes distincts :

Crée uniquement un port d’achèvement d’E/S sans l’associer à un descripteur de fichier.
Associe un port d’achèvement d’E/S existant à un descripteur de fichier.
Effectue à la fois la création et l’association dans un seul appel.

Pour créer un port d’achèvement d’E/S sans l’associer, définissez le paramètre FileHandle sur INVALID_HANDLE_VALUE, le paramètre ExistingCompletionPort sur NULL et le paramètre CompletionKey sur zéro (qui est ignoré dans ce cas). Attribue au paramètre NumberOfConcurrentThreads la valeur de concurrence souhaitée pour le nouveau port d’achèvement d’E/S, ou zéro pour la valeur par défaut (le nombre de processeurs dans le système).

Le descripteur transmis dans le paramètre FileHandle peut être n’importe quel descripteur prenant en charge les E/S qui se chevauchent. Le plus souvent, il s’agit d’un descripteur ouvert par la fonction CreateFile à l’aide de l’indicateur FILE_FLAG_OVERLAPPED (par exemple, les fichiers, les emplacements de messagerie et les canaux). Les objets créés par d’autres fonctions telles que les sockets peuvent également être associés à un port d’achèvement d’entrée/sortie. Pour un exemple d’utilisation des sockets, consultez AcceptEx. Un descripteur ne peut être associé qu’à un seul port d’achèvement d’E/S. Une fois l’association faite, le descripteur reste associé à ce port d’achèvement d’E/S jusqu’à ce qu’il soit fermé.

Pour plus d’informations sur la théorie, l’utilisation et les fonctions associées des ports d’achèvement des E/S, voir Ports d’achèvement des E/S.

Plusieurs descripteurs de fichiers peuvent être associés à un seul port d’achèvement d’E/S en appelant plusieurs fois CreateIoCompletionPort avec le même descripteur de port d’achèvement d’E/S dans le paramètre ExistingCompletionPort et un descripteur de fichier différent dans le paramètre FileHandle à chaque fois.

Utilisez le paramètre CompletionKey pour aider votre application à déterminer quelles opérations d’E/S sont terminées. Cette valeur n’est pas utilisée par CreateIoCompletionPort pour le contrôle fonctionnel ; elle est plutôt attachée au descripteur de fichier spécifié dans le paramètre FileHandle au moment de l’association avec un port d’achèvement d’E/S. Cette clé d’achèvement doit être unique pour chaque descripteur de fichier, et elle accompagne le descripteur de fichier tout au long de la procédure interne de mise en file d’attente d’achèvement. Il est renvoyé dans l’appel à la fonction GetQueuedCompletionStatus lorsqu’un paquet d’achèvement arrive. Le paramètre CompletionKey est également utilisé par la fonction PostQueuedCompletionStatus pour mettre en file d’attente vos propres paquets d’achèvement à usage spécial.

Une fois qu’une instance d’un descripteur ouvert est associée à un port d’achèvement d’E/S, elle ne peut pas être utilisée dans la fonction ReadFileEx ou WriteFileEx, car ces fonctions ont leurs propres mécanismes d’E/S asynchrones.

Il est préférable de ne pas partager un descripteur de fichier associé à un port d’achèvement d’E/S à l’aide de l’héritage de descripteur ou d’un appel à la fonction DuplicateHandle. Les opérations effectuées avec ces descripteurs dupliqués génèrent des notifications d’achèvement. Il est conseillé d’y réfléchir attentivement.

Le descripteur de port d’achèvement d’E/S et chaque descripteur de fichier associé à ce port d’achèvement d’E/S particulier sont appelés références au port d’achèvement des E/S. Le port d’achèvement des E/S est libéré lorsqu’il n’y a plus de références à ce port. Par conséquent, tous ces descripteurs doivent être correctement fermés pour libérer le port d’achèvement d’E/S et les ressources système associées. Une fois ces conditions remplies, fermez le descripteur du port d’achèvement des E/S en appelant la fonction CloseHandle.

Dans Windows 8 et Windows Server 2012, cette fonction est prise en charge par les technologies suivantes.

Technologie	Prise en charge
Protocole Server Message Block (SMB) 3.0	Oui
Basculement transparent SMB 3.0 (TFO)	Oui
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO)	Oui
Système de fichiers du volume partagé de cluster (CsvFS)	Oui
Système de fichiers résilient (ReFS)	Oui

Configuration requise


Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	ioapiset.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll