Fonction CloseThreadpoolCleanupGroupMembers (threadpoolapiset.h)

Article
03/04/2024

Libère les membres du groupe de nettoyage spécifié, attend que toutes les fonctions de rappel se terminent et annule éventuellement toutes les fonctions de rappel en suspens.

Syntaxe

void CloseThreadpoolCleanupGroupMembers(
  [in, out]           PTP_CLEANUP_GROUP ptpcg,
  [in]                BOOL              fCancelPendingCallbacks,
  [in, out, optional] PVOID             pvCleanupContext
);

Paramètres

[in, out] ptpcg

Pointeur vers une structure TP_CLEANUP_GROUP qui définit le groupe de nettoyage. La fonction CreateThreadpoolCleanupGroup retourne ce pointeur.

[in] fCancelPendingCallbacks

Si ce paramètre a la valeur TRUE, la fonction annule les rappels en attente qui n’ont pas encore démarré. Si ce paramètre a la valeur FALSE, la fonction attend que les fonctions de rappel en suspens se terminent.

[in, out, optional] pvCleanupContext

Données définies par l’application à passer à la fonction de rappel de groupe de nettoyage de l’application. Vous pouvez spécifier la fonction de rappel lorsque vous appelez SetThreadpoolCallbackCleanupGroup.

Valeur de retour

None

Remarques

La fonction CloseThreadpoolCleanupGroupMembers simplifie le nettoyage des objets de rappel de pool de threads en libérant, en une seule opération, tous les objets de travail, objets d’attente et objets minuteur qui sont membres du groupe de nettoyage. Un objet devient membre d’un groupe de nettoyage lorsque l’objet est créé avec l’environnement de rappel de threadpool spécifié lors de la création du groupe de nettoyage. Pour plus d’informations, consultez CreateThreadpoolCleanupGroup.

La fonction CloseThreadpoolCleanupGroupMembers est bloquée jusqu’à ce que toutes les fonctions de rappel en cours d’exécution se terminent. Si fCancelPendingCallbacks a la valeur TRUE, les rappels en attente sont annulés ; sinon, la fonction se bloque jusqu’à ce que tous les rappels en suspens se terminent également. Une fois la fonction CloseThreadpoolCleanupGroupMembers retournée, une application ne doit pas utiliser d’objet qui était membre du groupe de nettoyage au moment de l’appel de CloseThreadpoolCleanupGroupMembers . En outre, une application ne doit libérer aucun des objets individuellement en appelant une fonction telle que CloseThreadpoolWork, car les objets ont déjà été libérés.

La fonction CloseThreadpoolCleanupGroupMembers ne ferme pas le groupe de nettoyage lui-même. Au lieu de cela, le groupe de nettoyage persiste jusqu’à ce que la fonction CloseThreadpoolCleanupGroup soit appelée. En outre, la fermeture d’un groupe de nettoyage n’affecte pas l’environnement de rappel de threadpool associé. L’environnement de rappel persiste jusqu’à ce qu’il soit détruit en appelant DestroyThreadpoolEnvironment.

Tant qu’un groupe de nettoyage persiste, de nouveaux objets créés avec l’environnement de rappel de threadpool associé du groupe de nettoyage sont ajoutés au groupe de nettoyage. Cela permet à une application de réutiliser le groupe de nettoyage. Toutefois, cela peut entraîner des erreurs si l’application ne synchronise pas le code qui appelle CloseThreadpoolCleanupGroupMembers avec le code qui crée de nouveaux objets. Par exemple, supposons qu’un thread crée deux objets de travail threadpool, Work1 et Work2. Un autre thread appelle CloseThreadpoolCleanupGroupMembers. Selon le moment où les threads s’exécutent, l’un des événements suivants peut se produire :

Work1 et Work2 sont ajoutés au groupe de nettoyage après la publication de ses membres existants. Le code qui envoie Work1 et Work2 réussit.
Work1 est ajouté au groupe de nettoyage avant la publication de ses membres existants, ce qui entraîne la publication de Work1 avec d’autres membres. Ensuite, Work2 est ajouté. Le code qui envoie Work1 génère une exception ; le code qui envoie Work2 réussit.
Work1 et Work2 sont ajoutés au groupe de nettoyage avant la publication de ses membres existants, ce qui entraîne la publication de Work1 et Work2. Le code qui envoie Work1 ou Work2 génère une exception.

Pour simplement attendre ou annuler des éléments de travail en attente sans les libérer, utilisez l’une des fonctions de rappel de threadpool : WaitForThreadpoolIoCallbacks, WaitForThreadpoolTimerCallbacks, WaitForThreadpoolWaitCallbacks ou WaitForThreadpoolWorkCallbacks.

Pour compiler une application qui utilise cette fonction, définissez _WIN32_WINNT comme 0x0600 ou une version ultérieure.

Exemples

Pour obtenir un exemple, consultez Utilisation des fonctions de pool de threads.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	threadpoolapiset.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll