Função AvRtCreateThreadOrderingGroupExA (avrt.h)
Cria um grupo de ordenação de threads 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 thread é 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 esvaia antes de qualquer um ser 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 threads, 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 em 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 de tempo limite infinito. Isso pode ser útil para fins de depuração.
[in] TaskName
O nome da tarefa.
Valor de retorno
Se a função for bem-sucedida, o valor retornado não será 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.
Observações
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 do 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 coloca o código a ser executado durante cada período em 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 threads 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 threads.
#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
O cabeçalho avrt.h define AvRtCreateThreadOrderingGroupEx como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows Vista [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2008 [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | avrt.h |
| biblioteca | Avrt.lib |
| de DLL |
Avrt.dll |