Share via

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 [僅限傳統型應用程式]
目標平台 Windows
標頭 avrt.h
程式庫 Avrt.lib
Dll Avrt.dll

另請參閱

線程排序服務