ホーム › System.Threading › AvRtCreateThreadOrderingGroupExW

AvRtCreateThreadOrderingGroupExW

関数

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

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

シグネチャ

// AVRT.dll  (Unicode / -W)
#include <windows.h>

BOOL AvRtCreateThreadOrderingGroupExW(
    AVRT_THREAD_ORDERING_GROUP_HANDLE* Context,
    LONGLONG* Period,
    GUID* ThreadOrderingGuid,
    LONGLONG* Timeout,   // optional
    LPCWSTR 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	LPCWSTR	in	タスクの名前。

戻り値の型: BOOL

公式ドキュメント

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

戻り値

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

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

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

解説(Remarks)

呼び出し元のスレッドが親スレッドとみなされます。各スレッド順序付けグループには 1 つの親スレッドがあります。各親スレッドは 0 個以上の先行スレッドと 0 個以上の後続スレッドを持つことができます。クライアントスレッドは、AvRtJoinThreadOrderingGroup 関数を使用してスレッド順序付けグループに参加し、それが先行スレッドか後続スレッドかを指定できます。

親スレッドは、各周期中に実行するコードを AvRtWaitOnThreadOrderingGroup 関数によって制御されるループ内に囲みます。

スレッド順序付けグループを削除するには、AvRtDeleteThreadOrderingGroup 関数を呼び出します。

スレッドは複数のスレッド順序付けグループを作成し、複数のスレッド順序付けグループに参加できます。ただし、スレッドが同じスレッド順序付けグループに 2 回以上参加することはできません。

スレッド順序付けグループの親スレッドとクライアントスレッドは高い優先度で実行されます。ただし、スレッド順序付けグループを管理するサーバースレッドは通常の優先度で実行されます。そのため、他の高優先度スレッドが実行されている場合、あるクライアントスレッドから別のクライアントスレッドへの切り替えに遅延が生じることがあります。この関数の 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 版を自動的に選択するエイリアスとして定義します。エンコーディング中立のエイリアスを、エンコーディング中立でないコードと混在して使用すると、不一致が生じ、コンパイルエラーや実行時エラーを引き起こす可能性があります。詳細については、関数プロトタイプの規則を参照してください。

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

各言語での呼び出し定義

// AVRT.dll  (Unicode / -W)
#include <windows.h>

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

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

<DllImport("AVRT.dll", CharSet:=CharSet.Unicode, SetLastError:=True, ExactSpelling:=True)>
Public Shared Function AvRtCreateThreadOrderingGroupExW(
    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.LPWStr)> TaskName As String   ' LPCWSTR
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

' Context : AVRT_THREAD_ORDERING_GROUP_HANDLE* out
' Period : LONGLONG*
' ThreadOrderingGuid : GUID* in/out
' Timeout : LONGLONG* optional
' TaskName : LPCWSTR
Declare PtrSafe Function AvRtCreateThreadOrderingGroupExW Lib "avrt" ( _
    ByVal Context As LongPtr, _
    ByRef Period As LongLong, _
    ByVal ThreadOrderingGuid As LongPtr, _
    ByVal Timeout As LongPtr, _
    ByVal TaskName As LongPtr) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

AvRtCreateThreadOrderingGroupExW = ctypes.windll.avrt.AvRtCreateThreadOrderingGroupExW
AvRtCreateThreadOrderingGroupExW.restype = wintypes.BOOL
AvRtCreateThreadOrderingGroupExW.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.LPCWSTR,  # TaskName : LPCWSTR
]
# GetLastError: use ctypes.GetLastError() (or ctypes.WinDLL(use_last_error=True))

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('AVRT.dll')
AvRtCreateThreadOrderingGroupExW = Fiddle::Function.new(
  lib['AvRtCreateThreadOrderingGroupExW'],
  [
    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 : LPCWSTR
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"

#[link(name = "avrt")]
extern "system" {
    fn AvRtCreateThreadOrderingGroupExW(
        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 u16  // LPCWSTR
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

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

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

出力引数:

#uselib "AVRT.dll"
#cfunc global AvRtCreateThreadOrderingGroupExW "AvRtCreateThreadOrderingGroupExW" var, var, var, var, wstr
; res = AvRtCreateThreadOrderingGroupExW(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 : LPCWSTR -> "wstr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "AVRT.dll"
#cfunc global AvRtCreateThreadOrderingGroupExW "AvRtCreateThreadOrderingGroupExW" sptr, sptr, sptr, sptr, wstr
; res = AvRtCreateThreadOrderingGroupExW(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 : LPCWSTR -> "wstr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。