AvRtCreateThreadOrderingGroupExA 函数 (avrt.h)

  • 项目

创建线程排序组并将服务器线程与任务相关联。

语法

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

指向超时值的指针。 组内的所有线程都应在 Period 加 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 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求 值
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
目标平台 Windows
标头 avrt.h
Library Avrt.lib
DLL Avrt.dll

另请参阅

线程排序服务