Função AvRtCreateThreadOrderingGroupExA (avrt.h)

Cria um grupo de ordenação de thread e associa o thread do servidor a uma tarefa.

Sintaxe

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

Parâmetros

[out] Context

Um ponteiro para um identificador de contexto.

[in] Period

Um ponteiro para um valor, em incrementos de 100 nanossegundos, que especifica o período para o grupo de ordenação de threads. Cada thread no grupo de ordenação de threads é executado uma vez durante esse período. Se todos os threads concluirem a execução antes do término de um período, todos os threads aguardarão até que o restante do período se desaiba antes que qualquer seja executado novamente.

Os valores possíveis para esse parâmetro dependem da plataforma, mas esse parâmetro pode ser tão baixo quanto 500 microssegundos ou até 0x1FFFFFFFFFFFFFFF. Se esse parâmetro for menor que 500 microssegundos, ele será definido como 500 microssegundos. Se esse parâmetro for maior que o máximo, ele será definido como 0x1FFFFFFFFFFFFFFF.

[in, out] ThreadOrderingGuid

Um ponteiro para o identificador exclusivo para o grupo de ordenação de thread a ser criado. Se esse valor não for exclusivo do serviço de ordenação de thread, a função falhará.

Se o identificador for GUID_NULL na entrada, o serviço de ordenação de threads gerará e retornará um identificador exclusivo.

[in, optional] Timeout

Um ponteiro para um valor de tempo limite. Todos os threads dentro do grupo devem concluir a execução no Período mais Tempo limite.

Se um thread não concluir seu processamento dentro do período mais esse intervalo de tempo limite, ele será removido do grupo de ordenação de threads. Se o pai não concluir o processamento dentro do período mais o intervalo de tempo limite, o grupo de ordenação de threads será destruído.

Os valores possíveis para esse parâmetro dependem da plataforma, mas podem ser tão baixos quanto 500 microssegundos ou até 0x1FFFFFFFFFFFFFFF. Se esse parâmetro for menor que 500 microssegundos, ele será definido como 500 microssegundos. Se esse parâmetro for maior que o máximo, ele será definido como 0x1FFFFFFFFFFFFFFF.

Se esse parâmetro for NULL ou 0, o padrão será cinco vezes o valor de Period.

Se esse parâmetro for THREAD_ORDER_GROUP_INFINITE_TIMEOUT, o grupo será criado com um intervalo infinito de tempo limite. Isso pode ser útil para fins de depuração.

[in] TaskName

O nome da tarefa.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

Se já existir um grupo de ordenação de thread com o identificador especificado, a função falhará e definirá o último erro como ERROR_ALREADY_EXISTS.

Comentários

O thread de chamada é considerado o thread pai. Cada grupo de ordenação de threads tem um thread pai. Cada thread pai pode ter zero ou mais threads predecessores e zero ou mais threads sucessores. Um thread de cliente pode ingressar em um grupo de ordenação de threads e especificar se ele é um predecessor ou sucessor usando a função AvRtJoinThreadOrderingGroup .

O thread pai inclui o código a ser executado durante cada período dentro de um loop controlado pela função AvRtWaitOnThreadOrderingGroup .

Para excluir o grupo de ordenação de threads, chame a função AvRtDeleteThreadOrderingGroup .

Um thread pode criar mais de um grupo de ordenação de threads e ingressar em mais de um grupo de ordenação de threads. No entanto, um thread não pode ingressar no mesmo grupo de ordenação de thread mais de uma vez.

Os threads pai e cliente de um grupo de ordenação de thread são executados em altas prioridades. No entanto, o thread do servidor que gerencia o grupo de ordenação de threads é executado com prioridade normal. Portanto, pode haver um atraso ao alternar de um thread de cliente para outro se houver outros threads de alta prioridade em execução. O parâmetro TaskName dessa função especifica a tarefa a ser associada ao thread do servidor.

Exemplos

O snippet a seguir cria um grupo de ordenação de 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;
}

Requisitos

Confira também

Serviço de Ordenação de Threads