Share via

Funzione AvRtCreateThreadOrderingGroupExA (avrt.h)

  • Articolo

Crea un gruppo di ordinamento di 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 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.

[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 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.

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

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 = AvRtCreateThreadOrderingGroupEx( 
            &hContext,
            &period,
            &guid,
            &timeout,
            TEXT("Audio") );

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

    return 0;
}

Nota

L'intestazione avrt.h definisce AvRtCreateThreadOrderingGroupEx come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

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