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

タイムアウト値へのポインター。 グループ内のすべてのスレッドは、 Period と 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;
}

注意

avrt.h ヘッダーは AvRtCreateThreadOrderingGroupEx をエイリアスとして定義します。このエイリアスは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー avrt.h
Library Avrt.lib
[DLL] Avrt.dll

こちらもご覧ください

スレッド順序付けサービス