ホーム › System.Threading › AvRtCreateThreadOrderingGroup

AvRtCreateThreadOrderingGroup

関数

スレッド順序付けグループを作成する。

DLLAVRT.dll呼出規約winapiSetLastErrorあり対応OSWindows Vista 以降

シグネチャ

// AVRT.dll
#include <windows.h>

BOOL AvRtCreateThreadOrderingGroup(
    AVRT_THREAD_ORDERING_GROUP_HANDLE* Context,
    LONGLONG* Period,
    GUID* ThreadOrderingGuid,
    LONGLONG* Timeout   // optional
);

パラメーター

名前	型	方向	説明
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 の場合、グループは無限のタイムアウト間隔で作成されます。これはデバッグ目的に有用です。

戻り値の型: BOOL

公式ドキュメント

スレッド順序グループを作成します。

戻り値

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

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

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

解説(Remarks)

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

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

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

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

Examples

次のスニペットはスレッド順序グループを作成します。

#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 = AvRtCreateThreadOrderingGroup( 
            &hContext,
            &period,
            &guid,
            &timeout );

    if( bRes != TRUE )
    {
        printf("Error creating group (%d)\n", GetLastError());
            return 1;
    }

    return 0;
}

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

各言語での呼び出し定義

// AVRT.dll
#include <windows.h>

BOOL AvRtCreateThreadOrderingGroup(
    AVRT_THREAD_ORDERING_GROUP_HANDLE* Context,
    LONGLONG* Period,
    GUID* ThreadOrderingGuid,
    LONGLONG* Timeout   // optional
);

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

<DllImport("AVRT.dll", SetLastError:=True, ExactSpelling:=True)>
Public Shared Function AvRtCreateThreadOrderingGroup(
    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
) As <MarshalAs(UnmanagedType.Bool)> Boolean
End Function

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

import ctypes
from ctypes import wintypes

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

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('AVRT.dll')
AvRtCreateThreadOrderingGroup = Fiddle::Function.new(
  lib['AvRtCreateThreadOrderingGroup'],
  [
    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_INT)

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

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

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

出力引数:

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