共用方式為

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

逾時值的指標。 群組中的所有線程都應該在 期間內完成執行， 加上 逾時。

如果線程在期間內無法完成其處理，加上這個超時時間間隔，則會從線程排序群組中移除它。 如果父代無法在期間內完成其處理，加上超時時間間隔，線程排序群組就會終結。

此參數的可能值取決於平臺，但可以高達 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 標頭會根據 UNICODE 預處理器常數的定義，將 AvRtCreateThreadOrderingGroupEx 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的 慣例。

要求

要求 價值
最低支援的用戶端 Windows Vista [僅限傳統型應用程式]
支援的最低伺服器 Windows Server 2008 [僅限傳統型應用程式]
目標平臺 窗戶
標頭 avrt.h
連結庫 Avrt.lib
DLL Avrt.dll

另請參閱

線程排序服務