Fonction AvRtCreateThreadOrderingGroupExW (avrt.h)

Crée un groupe d’ordre de threads et associe le thread de serveur à une tâche.

Syntaxe

AVRTAPI BOOL AvRtCreateThreadOrderingGroupExW(
  [out]          PHANDLE        Context,
  [in]           PLARGE_INTEGER Period,
  [in, out]      GUID           *ThreadOrderingGuid,
  [in, optional] PLARGE_INTEGER Timeout,
  [in]           LPCWSTR        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 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.

[in] TaskName

Nom de la tâche.

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.

Les threads parent et client d’un groupe de tri des 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 à priorité normale. Par conséquent, il peut y avoir un délai de basculement d’un thread client à un autre s’il existe d’autres threads de 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 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 = AvRtCreateThreadOrderingGroupEx( 
            &hContext,
            &period,
            &guid,
            &timeout,
            TEXT("Audio") );

    if( bRes != TRUE )
    {
        printf("Error creating group (%d)\n", GetLastError());
            return 1;
    }

    return 0;
}

Notes

L’en-tête avrt.h définit AvRtCreateThreadOrderingGroupEx en tant qu’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. La combinaison 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.

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

Voir aussi

Service de classement des threads