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

Статья
11/20/2024

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

Синтаксис

AVRTAPI BOOL AvRtCreateThreadOrderingGroupExA(
  [out]          PHANDLE        Context,
  [in]           PLARGE_INTEGER Period,
  [in, out]      GUID           *ThreadOrderingGuid,
  [in, optional] PLARGE_INTEGER Timeout,
  [in]           LPCSTR         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, значение по умолчанию равно пять раз периоду.

Если этот параметр 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 [только классические приложения]
целевая платформа	Виндоус
заголовка	avrt.h
библиотеки	Avrt.lib
DLL	Avrt.dll

См. также

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

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