Fonction AvRtCreateThreadOrderingGroup (avrt.h)
Crée un groupe de tri des threads.
Pour éviter que le thread serveur du groupe de classement des threads ne soit affamé si des threads clients de priorité plus élevée sont en cours d’exécution, utilisez la fonction AvRtCreateThreadOrderingGroupEx .
Syntaxe
AVRTAPI BOOL AvRtCreateThreadOrderingGroup(
[out] PHANDLE Context,
[in] PLARGE_INTEGER Period,
[in, out] GUID *ThreadOrderingGuid,
[in, optional] PLARGE_INTEGER Timeout
);
Paramètres
[out] Context
Pointeur vers un handle de contexte.
[in] Period
Pointeur vers une valeur, par incréments de 100 nanosecondes, qui spécifie la période du groupe de tri des threads. Chaque thread du groupe de classement des threads s’exécute une fois pendant cette période. Si tous les threads terminent leur exécution avant la fin d’un point, tous les threads attendent que le reste de la période s’écoule avant qu’ils ne soient réexécutés.
Les valeurs possibles pour ce paramètre dépendent de la plateforme, mais ce paramètre peut être aussi bas que 500 microsecondes ou aussi élevé que 0x1FFFFFFFFFFFFFFF. Si ce paramètre est inférieur à 500 microsecondes, il est défini sur 500 microsecondes. Si ce paramètre est supérieur à la valeur maximale, il est défini sur 0x1FFFFFFFFFFFFFFF.
[in, out] ThreadOrderingGuid
Pointeur vers l’identificateur unique du groupe de tri des threads à créer. Si cette valeur n’est pas propre au service de classement des threads, la fonction échoue.
Si l’identificateur est GUID_NULL lors de l’entrée, le service de classement des threads génère et retourne un identificateur unique.
[in, optional] Timeout
Pointeur vers une valeur de délai d’attente. Tous les threads au sein du groupe doivent terminer leur exécution dans période plus délai d’expiration.
Si un thread ne parvient pas à terminer son traitement dans la période plus cet intervalle de délai d’attente, il est supprimé du groupe de classement des threads. Si le parent ne parvient pas à terminer son traitement dans la période plus l’intervalle de délai d’attente, le groupe d’ordre des threads est détruit.
Les valeurs possibles pour ce paramètre dépendent de la plateforme, mais peuvent être aussi basses que 500 microsecondes ou aussi élevées que 0x1FFFFFFFFFFFFFFF. Si ce paramètre est inférieur à 500 microsecondes, il est défini sur 500 microsecondes. Si ce paramètre est supérieur à la valeur maximale, il est défini sur 0x1FFFFFFFFFFFFFFF.
Si ce paramètre a la valeur NULL ou 0, la valeur par défaut est cinq fois la valeur de Period.
Si ce paramètre est THREAD_ORDER_GROUP_INFINITE_TIMEOUT, le groupe est créé avec un intervalle de délai d’attente infini. Cela peut être utile à des fins de débogage.
Valeur retournée
Si la fonction réussit, la valeur de retour est différente de zéro.
Si la fonction échoue, la valeur de retour est égale à zéro. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.
Si un groupe de classements de threads avec l’identificateur spécifié existe déjà, la fonction échoue et définit la dernière erreur sur ERROR_ALREADY_EXISTS.
Remarques
Le thread appelant est considéré comme le thread parent. Chaque groupe de classement de threads a un thread parent. Chaque thread parent peut avoir zéro ou plusieurs threads prédécesseurs et zéro ou plusieurs threads successeurs. Un thread client peut joindre un groupe d’ordre de threads et spécifier s’il s’agit d’un prédécesseur ou d’un successeur à l’aide de la fonction AvRtJoinThreadOrderingGroup .
Le thread parent entoure le code à exécuter pendant chaque période dans une boucle contrôlée par la fonction AvRtWaitOnThreadOrderingGroup .
Pour supprimer le groupe de classement des threads, appelez la fonction AvRtDeleteThreadOrderingGroup .
Un thread peut créer plusieurs groupes de classement de threads et joindre plusieurs groupes de classement de threads. Toutefois, un thread ne peut pas joindre le même groupe de tri des threads plusieurs fois.
Exemples
L’extrait de code suivant crée un groupe de tri des threads.
#include <windows.h>
#include <avrt.h>
#include <stdio.h>
#pragma comment(lib, "Avrt.lib")
#define _100NS_IN_1MS 10000
int main( void )
{
HANDLE hContext = NULL;
LARGE_INTEGER period, timeout;
GUID guid = { 0 };
BOOL bRes;
period.QuadPart = Int32x32To64(_100NS_IN_1MS, 1000); // 1 second
timeout.QuadPart = Int32x32To64(_100NS_IN_1MS, 10000); // 10 seconds
bRes = AvRtCreateThreadOrderingGroup(
&hContext,
&period,
&guid,
&timeout );
if( bRes != TRUE )
{
printf("Error creating group (%d)\n", GetLastError());
return 1;
}
return 0;
}
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows Vista [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | avrt.h |
| Bibliothèque | Avrt.lib |
| DLL | Avrt.dll |