AvRtCreateThreadOrderingGroupExA, fonction (avrt.h)
Crée un groupe d’ordre de threads et associe le thread de serveur à une tâche.
Syntaxe
AVRTAPI BOOL AvRtCreateThreadOrderingGroupExA(
[out] PHANDLE Context,
[in] PLARGE_INTEGER Period,
[in, out] GUID *ThreadOrderingGuid,
[in, optional] PLARGE_INTEGER Timeout,
[in] LPCSTR TaskName
);
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 d’ordre 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’une période, 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 faible 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 classement des threads à créer. Si cette valeur n’est pas unique au service d’ordre des threads, la fonction échoue.
Si l’identificateur est GUID_NULL sur l’entrée, le service d’ordre 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 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 d’ordre des threads. Si le parent ne parvient pas à terminer son traitement au cours de 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 est NULL ou 0, la valeur par défaut est cinq fois supérieure à la valeur de période.
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.
[in] TaskName
Nom de la tâche.
Valeur de retour
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’erreur étendues, appelez GetLastError.
Si un groupe d’ordre 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 d’ordre de thread 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 place 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 d’ordre de threads et joindre plusieurs groupes d’ordre de thread. Toutefois, un thread ne peut pas joindre le même groupe d’ordre de threads plusieurs fois.
Les threads parent et client d’un groupe d’ordre de threads s’exécutent à des priorités élevées. Toutefois, le thread de serveur qui gère le groupe d’ordre des threads s’exécute en priorité normale. Par conséquent, il peut y avoir un délai de passage d’un thread client à un autre s’il existe d’autres threads à priorité élevée en cours d’exécution. Le paramètre TaskName de cette fonction spécifie la tâche à associer au thread de serveur.
Exemples
L’extrait de code suivant crée un groupe d’ordre de 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 = AvRtCreateThreadOrderingGroupEx(
&hContext,
&period,
&guid,
&timeout,
TEXT("Audio") );
if( bRes != TRUE )
{
printf("Error creating group (%d)\n", GetLastError());
return 1;
}
return 0;
}
Note
L’en-tête avrt.h définit AvRtCreateThreadOrderingGroupEx comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows Vista [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2008 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | avrt.h |
| bibliothèque | Avrt.lib |
| DLL | Avrt.dll |