ホーム › System.Threading › AvRtCreateThreadOrderingGroupExA

AvRtCreateThreadOrderingGroupExA

関数

スレッド順序付けグループをタスク名指定で作成する(ANSI版)。

DLLAVRT.dll文字セットANSI (-A)呼出規約winapiSetLastErrorあり対応OSWindows Vista 以降

シグネチャ

// AVRT.dll  (ANSI / -A)
#include <windows.h>

BOOL AvRtCreateThreadOrderingGroupExA(
    AVRT_THREAD_ORDERING_GROUP_HANDLE* Context,
    LONGLONG* Period,
    GUID* ThreadOrderingGuid,
    LONGLONG* Timeout,   // optional
    LPCSTR TaskName
);

パラメーター

名前	型	方向	説明
Context	AVRT_THREAD_ORDERING_GROUP_HANDLE*	out	コンテキストハンドルへのポインター。
Period	LONGLONG*	in	スレッド順序付けグループの周期を指定する、100 ナノ秒単位の値へのポインター。スレッド順序付けグループ内の各スレッドは、この周期の間に 1 回実行されます。すべてのスレッドが周期の終了前に実行を完了した場合、いずれのスレッドも次に実行されるまで、周期の残り時間が経過するのを待機します。このパラメーターに指定できる値はプラットフォームに依存しますが、最小で 500 マイクロ秒、最大で 0x1FFFFFFFFFFFFFFF を指定できます。このパラメーターが 500 マイクロ秒未満の場合は、500 マイクロ秒に設定されます。最大値を超える場合は、0x1FFFFFFFFFFFFFFF に設定されます。
ThreadOrderingGuid	GUID*	inout	作成するスレッド順序付けグループの一意の識別子へのポインター。この値がスレッド順序付けサービス内で一意でない場合、関数は失敗します。入力時に識別子が GUID_NULL である場合、スレッド順序付けサービスが一意の識別子を生成して返します。
Timeout	LONGLONG*	inoptional	タイムアウト値へのポインター。グループ内のすべてのスレッドは、Period に Timeout を加えた時間内に実行を完了する必要があります。スレッドが周期にこのタイムアウト間隔を加えた時間内に処理を完了できない場合、そのスレッドはスレッド順序付けグループから削除されます。親スレッドが周期にタイムアウト間隔を加えた時間内に処理を完了できない場合、スレッド順序付けグループは破棄されます。このパラメーターに指定できる値はプラットフォームに依存しますが、最小で 500 マイクロ秒、最大で 0x1FFFFFFFFFFFFFFF を指定できます。このパラメーターが 500 マイクロ秒未満の場合は、500 マイクロ秒に設定されます。最大値を超える場合は、0x1FFFFFFFFFFFFFFF に設定されます。このパラメーターが NULL または 0 の場合、既定値は Period の値の 5 倍になります。このパラメーターが THREAD_ORDER_GROUP_INFINITE_TIMEOUT の場合、グループは無限のタイムアウト間隔で作成されます。これはデバッグの目的で役立つことがあります。
TaskName	LPCSTR	in	タスクの名前。

戻り値の型: BOOL

公式ドキュメント

スレッド順序付けグループを作成し、サーバースレッドをタスクに関連付けます。(ANSI)

戻り値

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

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

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

解説(Remarks)

呼び出し元のスレッドが親スレッドと見なされます。各スレッド順序付けグループには 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 ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして AvRtCreateThreadOrderingGroupEx を定義します。エンコーディング非依存のエイリアスの使用を、エンコーディング非依存ではないコードと混在させると、コンパイルエラーまたは実行時エラーを引き起こす不一致が生じる可能性があります。詳細については、関数プロトタイプの規約を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// AVRT.dll  (ANSI / -A)
#include <windows.h>

BOOL AvRtCreateThreadOrderingGroupExA(
    AVRT_THREAD_ORDERING_GROUP_HANDLE* Context,
    LONGLONG* Period,
    GUID* ThreadOrderingGuid,
    LONGLONG* Timeout,   // optional
    LPCSTR TaskName
);

[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("AVRT.dll", CharSet = CharSet.Ansi, SetLastError = true, ExactSpelling = true)]
static extern bool AvRtCreateThreadOrderingGroupExA(
    IntPtr Context,   // AVRT_THREAD_ORDERING_GROUP_HANDLE* out
    ref long Period,   // LONGLONG*
    ref Guid ThreadOrderingGuid,   // GUID* in/out
    IntPtr Timeout,   // LONGLONG* optional
    [MarshalAs(UnmanagedType.LPStr)] string TaskName   // LPCSTR
);

<DllImport("AVRT.dll", CharSet:=CharSet.Ansi, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function AvRtCreateThreadOrderingGroupExA(
    Context As IntPtr,   ' AVRT_THREAD_ORDERING_GROUP_HANDLE* out
    ByRef Period As Long,   ' LONGLONG*
    ByRef ThreadOrderingGuid As Guid,   ' GUID* in/out
    Timeout As IntPtr,   ' LONGLONG* optional
    <MarshalAs(UnmanagedType.LPStr)> TaskName As String   ' LPCSTR
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' Context : AVRT_THREAD_ORDERING_GROUP_HANDLE* out
' Period : LONGLONG*
' ThreadOrderingGuid : GUID* in/out
' Timeout : LONGLONG* optional
' TaskName : LPCSTR
Declare PtrSafe Function AvRtCreateThreadOrderingGroupExA Lib "avrt" ( _
    ByVal Context As LongPtr, _
    ByRef Period As LongLong, _
    ByVal ThreadOrderingGuid As LongPtr, _
    ByVal Timeout As LongPtr, _
    ByVal TaskName As String) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

AvRtCreateThreadOrderingGroupExA = ctypes.windll.avrt.AvRtCreateThreadOrderingGroupExA
AvRtCreateThreadOrderingGroupExA.restype = wintypes.BOOL
AvRtCreateThreadOrderingGroupExA.argtypes = [
    ctypes.c_void_p,  # Context : AVRT_THREAD_ORDERING_GROUP_HANDLE* out
    ctypes.POINTER(ctypes.c_longlong),  # Period : LONGLONG*
    ctypes.c_void_p,  # ThreadOrderingGuid : GUID* in/out
    ctypes.POINTER(ctypes.c_longlong),  # Timeout : LONGLONG* optional
    wintypes.LPCSTR,  # TaskName : LPCSTR
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('AVRT.dll')
AvRtCreateThreadOrderingGroupExA = Fiddle::Function.new(
  lib['AvRtCreateThreadOrderingGroupExA'],
  [
    Fiddle::TYPE_VOIDP,  # Context : AVRT_THREAD_ORDERING_GROUP_HANDLE* out
    Fiddle::TYPE_VOIDP,  # Period : LONGLONG*
    Fiddle::TYPE_VOIDP,  # ThreadOrderingGuid : GUID* in/out
    Fiddle::TYPE_VOIDP,  # Timeout : LONGLONG* optional
    Fiddle::TYPE_VOIDP,  # TaskName : LPCSTR
  ],
  Fiddle::TYPE_INT)

#[link(name = "avrt")]
extern "system" {
    fn AvRtCreateThreadOrderingGroupExA(
        Context: *mut AVRT_THREAD_ORDERING_GROUP_HANDLE,  // AVRT_THREAD_ORDERING_GROUP_HANDLE* out
        Period: *mut i64,  // LONGLONG*
        ThreadOrderingGuid: *mut GUID,  // GUID* in/out
        Timeout: *mut i64,  // LONGLONG* optional
        TaskName: *const u8  // LPCSTR
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[return: MarshalAs(UnmanagedType.Bool)]
[DllImport("AVRT.dll", CharSet = CharSet.Ansi, SetLastError = true)]
public static extern bool AvRtCreateThreadOrderingGroupExA(IntPtr Context, ref long Period, ref Guid ThreadOrderingGuid, IntPtr Timeout, [MarshalAs(UnmanagedType.LPStr)] string TaskName);
"@
$api = Add-Type -MemberDefinition $sig -Name 'AVRT_AvRtCreateThreadOrderingGroupExA' -Namespace Win32 -PassThru
# $api::AvRtCreateThreadOrderingGroupExA(Context, Period, ThreadOrderingGuid, Timeout, TaskName)

#uselib "AVRT.dll"
#func global AvRtCreateThreadOrderingGroupExA "AvRtCreateThreadOrderingGroupExA" sptr, sptr, sptr, sptr, sptr
; AvRtCreateThreadOrderingGroupExA varptr(Context), varptr(Period), varptr(ThreadOrderingGuid), varptr(Timeout), TaskName   ; 戻り値は stat
; Context : AVRT_THREAD_ORDERING_GROUP_HANDLE* out -> "sptr"
; Period : LONGLONG* -> "sptr"
; ThreadOrderingGuid : GUID* in/out -> "sptr"
; Timeout : LONGLONG* optional -> "sptr"
; TaskName : LPCSTR -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "AVRT.dll"
#cfunc global AvRtCreateThreadOrderingGroupExA "AvRtCreateThreadOrderingGroupExA" var, var, var, var, str
; res = AvRtCreateThreadOrderingGroupExA(Context, Period, ThreadOrderingGuid, Timeout, TaskName)
; Context : AVRT_THREAD_ORDERING_GROUP_HANDLE* out -> "var"
; Period : LONGLONG* -> "var"
; ThreadOrderingGuid : GUID* in/out -> "var"
; Timeout : LONGLONG* optional -> "var"
; TaskName : LPCSTR -> "str"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "AVRT.dll"
#cfunc global AvRtCreateThreadOrderingGroupExA "AvRtCreateThreadOrderingGroupExA" sptr, sptr, sptr, sptr, str
; res = AvRtCreateThreadOrderingGroupExA(varptr(Context), varptr(Period), varptr(ThreadOrderingGuid), varptr(Timeout), TaskName)
; Context : AVRT_THREAD_ORDERING_GROUP_HANDLE* out -> "sptr"
; Period : LONGLONG* -> "sptr"
; ThreadOrderingGuid : GUID* in/out -> "sptr"
; Timeout : LONGLONG* optional -> "sptr"
; TaskName : LPCSTR -> "str"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。