Функция AvRtCreateThreadOrderingGroupExW (avrt.h)

Статья
08/22/2023

Создает группу упорядочения потоков и связывает поток сервера с задачей.

Синтаксис

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

Параметры

[out] Context

Указатель на дескриптор контекста.

[in] Period

Указатель на значение с шагом в 100 наносекунд, указывающее период для группы упорядочения потоков. Каждый поток в группе упорядочивания потоков выполняется один раз в течение этого периода. Если все потоки завершают выполнение до окончания периода, все потоки ожидают, пока не закончится оставшаяся часть периода, прежде чем какие-либо из них будут выполнены снова.

Возможные значения этого параметра зависят от платформы, но этот параметр может быть не более 500 микросекунд или 0x1FFFFFFFFFFFFFFF. Если этот параметр меньше 500 микросекунд, ему присваивается значение 500 микросекунд. Если этот параметр больше максимального, то ему присваивается значение 0x1FFFFFFFFFFFFFFF.

[in, out] ThreadOrderingGuid

Указатель на уникальный идентификатор создаваемой группы упорядочения потоков. Если это значение не является уникальным для службы упорядочения потоков, функция завершается ошибкой.

Если идентификатор GUID_NULL на входных данных, служба упорядочивания потоков создает и возвращает уникальный идентификатор.

[in, optional] Timeout

Указатель на значение времени ожидания. Все потоки в группе должны завершить выполнение в пределах периода ивремени ожидания.

Если потоку не удается завершить обработку в течение периода плюс этот интервал времени ожидания, он удаляется из группы упорядочения потоков. Если родительскому элементу не удается завершить обработку в течение периода плюс интервал времени ожидания, группа упорядочения потоков уничтожается.

Возможные значения этого параметра зависят от платформы, но могут быть не более 500 микросекунд или 0x1FFFFFFFFFFFFFFF. Если этот параметр меньше 500 микросекунд, ему присваивается значение 500 микросекунд. Если этот параметр больше максимального, то ему присваивается значение 0x1FFFFFFFFFFFFFFF.

Если этот параметр имеет значение NULL или 0, значение по умолчанию в пять раз превышает значение Period.

Если этот параметр THREAD_ORDER_GROUP_INFINITE_TIMEOUT, группа создается с бесконечным интервалом времени ожидания. Это может быть полезно для отладки.

[in] TaskName

Имя данной задачи.

Возвращаемое значение

Если функция выполняется успешно, возвращается ненулевое значение.

Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Если группа упорядочения потоков с указанным идентификатором уже существует, функция завершается ошибкой и задает для последней ошибки значение ERROR_ALREADY_EXISTS.

Вызывающий поток считается родительским потоком. Каждая группа упорядочения потоков имеет один родительский поток. Каждый родительский поток может иметь ноль или более потоков-предшественников и ноль или более последующих потоков. Клиентский поток может присоединиться к группе упорядочения потоков и указать, является ли он предшественником или преемником, с помощью функции AvRtJoinThreadOrderingGroup .

Родительский поток содержит код, выполняемый в течение каждого периода, в цикле, управляемом функцией AvRtWaitOnThreadOrderingGroup .

Чтобы удалить группу упорядочения потоков, вызовите функцию AvRtDeleteThreadOrderingGroup .

Поток может создать несколько групп упорядочения потоков и объединить несколько групп упорядочения потоков. Однако поток не может объединять одну и ту же группу упорядочения потоков более одного раза.

Родительский и клиентский потоки группы упорядочения потоков выполняются с высоким приоритетом. Однако поток сервера, который управляет группой упорядочения потоков, выполняется с обычным приоритетом. Таким образом, при выполнении других высокоприоритетных потоков может возникнуть задержка переключения с одного клиентского потока на другой. Параметр TaskName этой функции указывает задачу, связанную с потоком сервера.

Примеры

Следующий фрагмент кода создает группу упорядочения потоков.

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

Примечание

Заголовок avrt.h определяет AvRtCreateThreadOrderingGroupEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [только классические приложения]
Минимальная версия сервера	Windows Server 2008 [только классические приложения]
Целевая платформа	Windows
Header	avrt.h
Библиотека	Avrt.lib
DLL	Avrt.dll

См. также раздел

Служба упорядочения потоков

Поделиться через