Share via

Funzione AvRtCreateThreadOrderingGroup (avrt.h)

  • Articolo

Crea un gruppo di ordinamento del thread.

Per impedire l'esecuzione del thread del gruppo di ordinamento del thread se vengono eseguiti thread client con priorità superiore, usare la funzione AvRtCreateThreadOrderingGroupEx .

Sintassi

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

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 del thread. Ogni thread nel gruppo di ordinamento del 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 attendeno fino al resto del periodo trascorso prima di eseguire di nuovo qualsiasi thread.

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 massimo, è impostato su 0x1FFFFFFFFFFFFFFF.

[in, out] ThreadOrderingGuid

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

Se l'identificatore è GUID_NULL in input, il servizio di ordinamento del 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 all'interno del 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 del 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.

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 massimo, è 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 per scopi di debug.

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 informazioni dettagliate sull'errore, chiamare GetLastError.

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

Commenti

Il thread chiamante è considerato il thread padre. Ogni gruppo di ordinamento del 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ò aggiungere un gruppo di ordinamento thread e specificare se è un predecessore o un 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 del thread, chiamare la funzione AvRtDeleteThreadOrderingGroup .

Un thread può creare più di un gruppo di ordinamento thread e aggiungere più di un gruppo di ordinamento thread. Tuttavia, un thread non può unire lo stesso gruppo di ordinamento thread più di una volta.

Esempio

Il frammento di codice seguente crea un gruppo di ordinamento 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 = AvRtCreateThreadOrderingGroup( 
            &hContext,
            &period,
            &guid,
            &timeout );

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

    return 0;
}

Requisiti

Requisito Valore
Client minimo supportato Windows Vista [solo app desktop]
Server minimo supportato Windows Server 2008 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione avrt.h
Libreria Avrt.lib
DLL Avrt.dll

Vedi anche

Servizio ordinamento thread