Funzione AvRtCreateThreadOrderingGroupExA (avrt.h)

Crea un gruppo di ordinamento dei thread e associa il thread del server a un'attività.

Sintassi

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

Parametri

[out] Context

Puntatore a un handle di contesto.

[in] Period

Puntatore a un valore, in incrementi di 100 nanosecondi, che specifica il periodo per il gruppo di ordinamento dei thread. Ogni thread nel gruppo di ordinamento dei thread viene eseguito una sola volta durante questo periodo. Se tutti i thread completano l'esecuzione prima del termine di un periodo, tutti i thread attendono fino a quando non scade il resto del periodo prima che venga eseguito di nuovo.

I valori possibili per questo parametro dipendono dalla piattaforma, ma questo parametro può essere inferiore a 500 microsecondi o al massimo 0x1FFFFFFFFFFFFFFF. Se questo parametro è minore di 500 microsecondi, viene impostato su 500 microsecondi. Se questo parametro è maggiore del valore massimo, viene impostato su 0x1FFFFFFFFFFFFFFF.

[in, out] ThreadOrderingGuid

Puntatore all'identificatore univoco del gruppo di ordinamento del thread da creare. Se questo valore non è univoco per il servizio di ordinamento dei thread, la funzione ha esito negativo.

Se l'identificatore è GUID_NULL all'input, il servizio di ordinamento dei thread genera e restituisce un identificatore univoco.

[in, optional] Timeout

Puntatore a un valore di timeout. Tutti i thread all'interno del gruppo devono completare l'esecuzione entro periodo più timeout.

Se un thread non riesce a completare l'elaborazione entro il periodo più questo intervallo di timeout, viene rimosso dal gruppo di ordinamento dei thread. Se l'elemento padre non riesce a completare l'elaborazione entro il periodo più l'intervallo di timeout, il gruppo di ordinamento del thread viene eliminato definitivamente.

I valori possibili per questo parametro dipendono dalla piattaforma, ma possono essere inferiori a 500 microsecondi o al massimo 0x1FFFFFFFFFFFFFFF. Se questo parametro è minore di 500 microsecondi, viene impostato su 500 microsecondi. Se questo parametro è maggiore del valore massimo, viene impostato su 0x1FFFFFFFFFFFFFFF.

Se questo parametro è NULL o 0, il valore predefinito è cinque volte il valore di Period.

Se questo parametro è THREAD_ORDER_GROUP_INFINITE_TIMEOUT, il gruppo viene creato con un intervallo di timeout infinito. Questo può essere utile a scopo di debug.

[in] TaskName

Nome dell'attività.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è diverso da zero.

Se la funzione ha esito negativo, il valore restituito è zero. Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Se esiste già un gruppo di ordinamento di thread con l'identificatore specificato, la funzione ha esito negativo e imposta l'ultimo errore su ERROR_ALREADY_EXISTS.

Osservazioni

Il thread chiamante è considerato il thread padre. Ogni gruppo di ordinamento dei thread ha un thread padre. Ogni thread padre può avere zero o più thread predecessori e zero o più thread successori. Un thread client può unire un gruppo di ordinamento di thread e specificare se è un predecessore o successore usando la funzione AvRtJoinThreadOrderingGroup.

Il thread padre racchiude il codice da eseguire durante ogni periodo all'interno di un ciclo controllato dalla funzione AvRtWaitOnThreadOrderingGroup.

Per eliminare il gruppo di ordinamento dei thread, chiamare la funzione AvRtDeleteThreadOrderingGroup.

Un thread può creare più di un gruppo di ordinamento di thread e creare un join di più di un gruppo di ordinamento di thread. Tuttavia, un thread non può unire lo stesso gruppo di ordinamento thread più volte.

I thread padre e client di un gruppo di ordinamento dei thread vengono eseguiti con priorità elevate. Tuttavia, il thread del server che gestisce il gruppo di ordinamento dei thread viene eseguito con priorità normale. Pertanto, può verificarsi un ritardo nel passaggio da un thread client a un altro se sono in esecuzione altri thread ad alta priorità. Il parametro TaskName di questa funzione specifica l'attività da associare al thread del server.

Esempi

Il frammento di codice seguente crea un gruppo di ordinamento dei thread.

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

Fabbisogno

Vedere anche

del servizio di ordinamento dei thread