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 |