AvRtCreateThreadOrderingGroup 函式 (avrt.h)

建立線程排序群組。

若要防止線程排序群組的伺服器線程在較高的優先順序用戶端線程執行時耗盡，請使用 AvRtCreateThreadOrderingGroupEx 函式。

語法

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

參數

[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，則會使用無限的逾時間隔來建立群組。 這對於偵錯用途很有用。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。

如果具有指定標識碼的線程排序群組已經存在，則函式會失敗，並將最後一個錯誤設定為ERROR_ALREADY_EXISTS。

備註

呼叫線程會被視為父線程。 每個線程排序群組都有一個父線程。 每個父線程可以有零個或多個前置線程，以及零個或多個後續線程。 用戶端線程可以聯結線程排序群組，並使用 AvRtJoinThreadOrderingGroup 函式來指定它是前置任務或後續任務。

父線程會在 AvRtWaitOnThreadOrderingGroup 函式所控制的循環內，封入要在每個期間內執行的程式碼。

若要刪除線程排序群組，請呼叫 AvRtDeleteThreadOrderingGroup 函式。

線程可以建立多個線程排序群組，並聯結多個線程排序群組。 不過，線程無法聯結同一個線程排序群組一次以上。

範例

下列代碼段會建立線程排序群組。

#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 = AvRtCreateThreadOrderingGroup( 
            &hContext,
            &period,
            &guid,
            &timeout );

    if( bRes != TRUE )
    {
        printf("Error creating group (%d)\n", GetLastError());
            return 1;
    }

    return 0;
}

規格需求

需求	值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	avrt.h
程式庫	Avrt.lib
Dll	Avrt.dll

另請參閱

線程排序服務