AvRtCreateThreadOrderingGroupExA-Funktion (avrt.h)
Erstellt eine Threadanordnungsgruppe und ordnet den Serverthread einer Aufgabe zu.
Syntax
AVRTAPI BOOL AvRtCreateThreadOrderingGroupExA(
[out] PHANDLE Context,
[in] PLARGE_INTEGER Period,
[in, out] GUID *ThreadOrderingGuid,
[in, optional] PLARGE_INTEGER Timeout,
[in] LPCSTR TaskName
);
Parameter
[out] Context
Ein Zeiger auf ein Kontexthandle.
[in] Period
Ein Zeiger auf einen Wert in 100-Nanosekunden-Schritten, der den Punkt für die Threadsortierungsgruppe angibt. Jeder Thread in der Threadbestellungsgruppe wird während dieses Zeitraums einmal ausgeführt. Wenn alle Threads ihre Ausführung vor dem Ende eines Punkts abschließen, warten alle Threads, bis der Rest des Zeitraums verstrichen ist, bevor sie erneut ausgeführt werden.
Die möglichen Werte für diesen Parameter sind von der Plattform abhängig, aber dieser Parameter kann bis zu 500 Mikrosekunden oder so hoch wie 0x1FFFFFFFFFFFFFFF sein. Wenn dieser Parameter kleiner als 500 Mikrosekunden ist, wird er auf 500 Mikrosekunden festgelegt. Wenn dieser Parameter größer als das Maximum ist, wird er auf 0x1FFFFFFFFFFFFFFF festgelegt.
[in, out] ThreadOrderingGuid
Ein Zeiger auf den eindeutigen Bezeichner für die zu erstellende Threadsortierungsgruppe. Wenn dieser Wert nicht für den Threadbestellungsdienst eindeutig ist, schlägt die Funktion fehl.
Wenn der Bezeichner bei der Eingabe GUID_NULL ist, generiert der Threadbestellungsdienst und gibt einen eindeutigen Bezeichner zurück.
[in, optional] Timeout
Ein Zeiger auf einen Timeoutwert. Alle Threads innerhalb der Gruppe sollten ihre Ausführung innerhalb Zeitraums plus Timeout-abschließen.
Wenn ein Thread die Verarbeitung innerhalb des Zeitraums und dieses Timeoutintervalls nicht abschließen kann, wird er aus der Thread-Sortiergruppe entfernt. Wenn das übergeordnete Element die Verarbeitung innerhalb des Zeitraums und des Timeoutintervalls nicht abschließen kann, wird die Threadgeordnetegruppe zerstört.
Die möglichen Werte für diesen Parameter hängen von der Plattform ab, können jedoch bis zu 500 Mikrosekunden oder so hoch wie 0x1FFFFFFFFFFFFFFF sein. Wenn dieser Parameter kleiner als 500 Mikrosekunden ist, wird er auf 500 Mikrosekunden festgelegt. Wenn dieser Parameter größer als das Maximum ist, wird er auf 0x1FFFFFFFFFFFFFFF festgelegt.
Wenn dieser Parameter NULL- oder 0 ist, ist der Standardwert fünfmal der Wert Period.
Wenn dieser Parameter THREAD_ORDER_GROUP_INFINITE_TIMEOUT ist, wird die Gruppe mit einem unendlichen Timeoutintervall erstellt. Dies kann für Debuggingzwecke nützlich sein.
[in] TaskName
Der Name des Vorgangs.
Rückgabewert
Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.
Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.
Wenn bereits eine Threadanordnungsgruppe mit dem angegebenen Bezeichner vorhanden ist, schlägt die Funktion fehl und legt den letzten Fehler auf ERROR_ALREADY_EXISTS fest.
Bemerkungen
Der aufrufende Thread wird als übergeordneter Thread betrachtet. Jede Threadgeordnetegruppe verfügt über einen übergeordneten Thread. Jeder übergeordnete Thread kann null oder mehr Vorgängerthreads und null oder mehr Nachfolgerthreads aufweisen. Ein Clientthread kann einer Threadsortierungsgruppe beitreten und angeben, ob es sich um einen Vorgänger oder Nachfolger handelt, indem die AvRtJoinThreadOrderingGroup--Funktion verwendet wird.
Der übergeordnete Thread schließt den Code ein, der während jeder Periode in einer Schleife ausgeführt werden soll, die von der AvRtWaitOnThreadOrderingGroup--Funktion gesteuert wird.
Rufen Sie zum Löschen der Threadsortierungsgruppe die AvRtDeleteThreadOrderingGroup--Funktion auf.
Ein Thread kann mehr als eine Threadbestellungsgruppe erstellen und mehreren Thread-Sortiergruppen beitreten. Ein Thread kann jedoch nicht mehrmals derselben Threadfolgegruppe beitreten.
Die übergeordneten und Clientthreads einer Threadgeordnetengruppe werden mit hohen Prioritäten ausgeführt. Der Serverthread, der die Threadbestellungsgruppe verwaltet, wird jedoch mit normaler Priorität ausgeführt. Daher kann ein Verzögerungswechsel von einem Clientthread zu einem anderen auftreten, wenn andere Threads mit hoher Priorität ausgeführt werden. Der TaskName Parameter dieser Funktion gibt die Aufgabe an, die dem Serverthread zugeordnet werden soll.
Beispiele
Der folgende Codeausschnitt erstellt eine Threadanordnungsgruppe.
#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;
}
Anmerkung
Der avrt.h-Header definiert AvRtCreateThreadOrderingGroupEx als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows Vista [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows Server 2008 [Nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | avrt.h |
| Library | Avrt.lib |
| DLL- | Avrt.dll |