AvRtCreateThreadOrderingGroup-Funktion (avrt.h)

Erstellt eine Threadreihenfolgegruppe.

Um zu verhindern, dass der Serverthread für die Threadreihenfolgegruppe ausgehungert wird, wenn Clientthreads mit höherer Priorität ausgeführt werden, verwenden Sie die AvRtCreateThreadOrderingGroupEx-Funktion .

Syntax

AVRTAPI BOOL AvRtCreateThreadOrderingGroup(
  [out]          PHANDLE        Context,
  [in]           PLARGE_INTEGER Period,
  [in, out]      GUID           *ThreadOrderingGuid,
  [in, optional] PLARGE_INTEGER Timeout
);

Parameter

[out] Context

Ein Zeiger auf ein Kontexthandle.

[in] Period

Ein Zeiger auf einen Wert in Schritten von 100 Nanosekunden, der den Zeitraum für die Threadreihenfolgegruppe angibt. Jeder Thread in der Threadreihenfolgegruppe wird in diesem Zeitraum einmal ausgeführt. Wenn alle Threads ihre Ausführung abgeschlossen haben, bevor ein Punkt endet, warten alle Threads, bis der Verbleibende des Zeitraums verstrichen ist, bevor sie erneut ausgeführt werden.

Die möglichen Werte für diesen Parameter hängen von der Plattform ab, 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 Threadreihenfolgegruppe. Wenn dieser Wert nicht für den Threadreihenfolgedienst eindeutig ist, schlägt die Funktion fehl.

Wenn der Bezeichner bei der Eingabe GUID_NULL wird, generiert und gibt der Threadreihenfolgedienst einen eindeutigen Bezeichner zurück.

[in, optional] Timeout

Ein Zeiger auf einen Timeoutwert. Alle Threads innerhalb der Gruppe sollten ihre Ausführung innerhalb von Zeitraum und Timeout abschließen.

Wenn ein Thread seine Verarbeitung innerhalb des Zeitraums und dieses Timeoutintervalls nicht abschließen kann, wird er aus der Threadreihenfolgegruppe entfernt. Wenn das übergeordnete Element die Verarbeitung innerhalb des Zeitraums und des Timeoutintervalls nicht abgeschlossen hat, wird die Threadreihenfolgegruppe zerstört.

Die möglichen Werte für diesen Parameter hängen von der Plattform ab, können aber 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 das Fünffache des Werts von 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.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Wenn bereits eine Threadreihenfolgegruppe mit dem angegebenen Bezeichner vorhanden ist, schlägt die Funktion fehl und legt den letzten Fehler auf ERROR_ALREADY_EXISTS fest.

Hinweise

Der aufrufende Thread wird als übergeordneter Thread betrachtet. Jede Threadreihenfolgegruppe hat einen übergeordneten Thread. Jeder übergeordnete Thread kann null oder mehr Vorgängerthreads und null oder mehr Nachfolgerthreads haben. Ein Clientthread kann eine Threadreihenfolgegruppe verknüpfen und mithilfe der AvRtJoinThreadOrderingGroup-Funktion angeben, ob es sich um einen Vorgänger oder einen Nachfolger handelt.

Der übergeordnete Thread schließt den Code, der während jedes Zeitraums ausgeführt werden soll, in eine Schleife ein, die von der AvRtWaitOnThreadOrderingGroup-Funktion gesteuert wird.

Um die Threadreihenfolgegruppe zu löschen, rufen Sie die Funktion AvRtDeleteThreadOrderingGroup auf.

Ein Thread kann mehr als eine Threadreihenfolgegruppe erstellen und mehrere Threadreihenfolgegruppen verknüpfen. Ein Thread kann jedoch nicht mehr als einmal derselben Threadreihenfolgegruppe beitreten.

Beispiele

Mit dem folgenden Codeausschnitt wird eine Threadreihenfolgegruppe erstellt.

#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;
}

Anforderungen

Weitere Informationen

Threadreihenfolgedienst