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 ナノ秒単位の値へのポインター。 スレッド順序付けグループ内の各スレッドは、この期間中に 1 回実行されます。 期間が終了する前にすべてのスレッドが実行を完了した場合、すべてのスレッドは、期間の残りの部分が経過するまで待機してから、もう一度実行されます。

このパラメーターに指定できる値はプラットフォームによって異なりますが、このパラメーターは 500 マイクロ秒以下、または0x1FFFFFFFFFFFFFFFまで高くすることができます。 このパラメーターが 500 マイクロ秒未満の場合は、500 マイクロ秒に設定されます。 このパラメーターが最大値より大きい場合は、0x1FFFFFFFFFFFFFFFに設定されます。

[in, out] ThreadOrderingGuid

作成するスレッド順序グループの一意識別子へのポインター。 この値がスレッド順序サービスに固有でない場合、関数は失敗します。

識別子が入力時にGUID_NULLされている場合、スレッド注文サービスは一意の識別子を生成して返します。

[in, optional] Timeout

タイムアウト値へのポインター。 グループ内のすべてのスレッドは、期間タイムアウト内で実行を完了する必要があります。

スレッドがこのタイムアウト間隔を加えた期間内に処理を完了できなかった場合は、スレッド順序付けグループから削除されます。 親が期間内に処理を完了できず、タイムアウト間隔を加えた場合、スレッド順序グループは破棄されます。

このパラメーターに指定できる値はプラットフォームによって異なりますが、500 マイクロ秒以下、または0x1FFFFFFFFFFFFFFFまで高くすることができます。 このパラメーターが 500 マイクロ秒未満の場合は、500 マイクロ秒に設定されます。 このパラメーターが最大値より大きい場合は、0x1FFFFFFFFFFFFFFFに設定されます。

このパラメーターが NULL または 0 場合、既定値は Periodの値の 5 倍になります。

このパラメーターがTHREAD_ORDER_GROUP_INFINITE_TIMEOUT場合、グループは無限のタイムアウト間隔で作成されます。 これは、デバッグの目的で役立ちます。

[in] TaskName

タスクの名前。

戻り値

関数が成功した場合、戻り値は 0 以外です。

関数が失敗した場合、戻り値は 0 です。 拡張エラー情報を取得するには、GetLastError呼び出します。

指定した識別子を持つスレッド順序付けグループが既に存在する場合、関数は失敗し、最後のエラーをERROR_ALREADY_EXISTSに設定します。

備考

呼び出し元のスレッドは親スレッドと見なされます。 各スレッド順序グループには、1 つの親スレッドがあります。 各親スレッドには、0 個以上の先行スレッドと 0 個以上の後続スレッドを含めることができます。 クライアント スレッドは、スレッド順序付けグループに参加し、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;
}

必要条件

関連項目

スレッド注文サービスの