MGL::Task各種定義

概要

MGL::Taskで定義されている、タスクシステムに関わる定義です。APIの情報についてはMGL::Taskを参照してください。

タスクシステムの使用方法についてはタスクシステムを参照してください。

型、列挙型

種類	名前	内容	バージョン
型	Identifier	タスクの種類を判別するための識別子の型	1.0.0+
型	UniqueIdentifier	タスクのユニークIDを表す型	1.0.0+
型	ExecuteStage	タスクの実行ステージ	1.0.0+
型	EventIdentifier	イベントの種類を判別するための識別子の型	1.0.0+
型	StageSettingsArray	実行ステージ設定の配列	1.0.0+
列挙型	ResideLevel	常駐レベル	1.1.0+
列挙型	ExecuteMode	タスクの実行モード	1.0.0+

構造体

種類	名前	内容	バージョン
構造体	StageSettings	実行ステージ設定	1.0.0+
構造体	InitializeDescriptor	初期化記述子	1.0.0+

定数

種類	名前	内容	バージョン
定数	kExecuteStageMax	実行ステージの最大数	1.0.0+

---

Identifier

タスクの種類を判別するための識別子の型

宣言

namespace MGL::Task
{
    enum class Identifier : uint32_t;
}

説明

タスクノードの種類ごとに割り当てる値を表すための型です。

この値の内容はアプリケーションごとに定義して各々のタスクに割り当てる必要があります。詳しくは基本的な使い方のタスクシステムを参照してください。

バージョン情報

MGL 1.0.0

• 初回リリース

関連

• 基本的な使い方-タスクシステム

---

UniqueIdentifier

タスクのユニークIDを表す型

宣言

namespace MGL::Task
{
    enum class UniqueIdentifier : uint64_t
    {
        Invalid = 0,
        Start = 1,
        End = ~static_cast<std::underlying_type<UniqueIdentifier>::type>(0),
    };
}

説明

各タスクノードに割り当てられる一意の値を格納するための型です。

ユニークIDはタスクノードが生成される際に自動で割り振られ、主にタスクの判別のために使用されます。アプリケーション側からはこの型の具体的な値を意識する必要はありません。

予約値として定義されているInvalid、Start、EndはMGLが内部的に使用する値であり、通常はアプリケーション側から使用することはありません。

バージョン情報

MGL 1.0.0

• 初回リリース

---

ExecuteStage

タスクの実行ステージ

宣言

namespace MGL::Task
{
    using ExecuteStage = uint8_t;
}

説明

タスクの実行ステージを格納するための型です。

タスクは1回あたりの更新を複数のステージに分割して実行可能であり、実行ステージを識別するためにこの型の値が使用されます。実行ステージの詳細についてはタスクシステムの実行ステージを参照してください。

なお、この型が表す値は識別のためのみに使用されます。実行順序についてはStageSettingsArrayの格納順によって確定し、この型の値は影響しない事にご注意ください。

有効な実行ステージの最大値はkExecuteStageMaxにて定義されています。

バージョン情報

MGL 1.0.0

• 初回リリース

関連

• kExecuteStageMax

• タスクシステム-実行ステージ

---

EventIdentifier

イベントの種類を判別するための識別子の型

宣言

namespace MGL::Task
{
    enum class EventIdentifier : uint32_t;
}

説明

タスクへのイベント通知を行う際に、その通知の種類を表す値に使用するための型です。この型で表される値はアプリケーション毎に独自に定義することを想定しています。

イベント通知に関する詳しい情報はタスクシステムのイベント通知を参照してください。

バージョン情報

MGL 1.0.0

• 初回リリース

関連

• MGL::Task::NotifyEvent

• MGL::Task::Node::OnReceiveTaskEvent

---

StageSettingsArray

実行ステージ設定の配列

宣言

namespace MGL::Task
{
    using StageSettingsArray = STL::vector<StageSettings>;
}

説明

実行ステージの設定を格納するための配列のエイリアスです。この配列をInitializeDescriptorへと設定し、MGL::Task::Initializeへと渡すことによってタスクシステムに実行ステージ設定を適用します。

実行ステージはこの配列に設定したインデックスの順に実行されます。StageSettingsが持つExecuteStage は実行順序に影響しない事にご注意ください。

バージョン情報

MGL 1.0.0

• 初回リリース

関連

• InitializeDescriptor

• StageSettings

• MGL::Task::Initialize

---

ResideLevel

常駐レベル

宣言

namespace MGL::Task
{
    enum class ResideLevel : uint8_t
    {
        NoResident  = 0,
        Low         = 0x40,
        Middle      = 0x70,
        High        = 0xB0,
        Max         = 0xFF,
    };
}

説明

タスクに設定可能な常駐レベルを表す定義です。

常駐レベルは複数のタスクをまとめて削除する場合に使用する値です。各タスクの常駐レベルが指定値以下だった場合、そのタスクは削除対象となります。

詳細はMGL::Task::Killを参照してください。

バージョン情報

MGL 1.1.0

• 初回リリース

関連

• MGL::Task::Kill

• MGL::Task::DestroyThemAll

---

ExecuteMode

タスクの実行モード

宣言

namespace MGL::Task
{
    enum class ExecuteMode : uint8_t
    {
        NormalUpdate,
        ParallelizableUpdate,
        RenderUpdate,
    };
}

説明

各実行ステージに割り当てられる実行モードの定義です。

各々の実行ステージにはいずれかの実行モードが割り当てられ、MGL::Task::Node::OnExecuteの実行方法が変化します。具体的な内容は次の通りです。

NormalUpdate

一般的な更新処理を行うためのモードです。

このモードは優先順位の高いタスクノードから逐次的に実行されます。複数のタスクノードが同時に実行されることはなく、常にMGL::Task::Executeの呼び出しスレッドのみで実行されます。

ParallelizableUpdate

更新処理の並列化を可能にするためのモードです。

このモードを設定した実行ステージにおいては、MGL::Task::Node::SetAsynchronousで非同期実行を設定したタスクノードを異なるスレッドで実行します。非同期実行を設定していないタスクノードや、タスク実行用のスレッドプールが利用できない環境においてはNormalUpdateと同じ動作となります。

並列実行に関する詳しい情報はタスクシステムのタスクの並列実行を参照してください。

RenderUpdate

描画用に特化したモードです。

各タスクの描画に関わる処理は、このモードが設定された実行ステージ内で行うことを強く推奨します。

注釈

現時点ではこのモードはNormalUpdateと同じ動作を行いますが、将来的に描画とそれ以外の実行周期を分ける機能の導入を計画しています。今後の拡張に特別な修正なしに対応できるよう、描画処理はこのモード内で実行することを推奨しています。

バージョン情報

MGL 1.1.11

• 初回リリース

MGL 1.1.13

• 型のサイズにuint8_tを指定

関連

• MGL::Task::Execute

• MGL::Task::Node::OnExecute

• MGL::Task::Node::SetAsynchronous

---

StageSettings

実行ステージ設定

宣言

namespace MGL::Task
{
    struct StageSettings
    {
        ExecuteStage stage;
        ExecuteMode mode;

        constexpr StageSettings(ExecuteStage inStage, ExecuteMode inMode) noexcept;
    }
}

説明

タスクシステムの初期化時に渡す実行ステージ設定を格納するための構造体です。

この構造体は1つの実行ステージに対する設定情報を格納するために使用されます。この構造体を配列化したStageSettingsArrayで全体の実行ステージ設定を表し、これをInitializeDescriptorのメンバに設定してMGL::Task::Initializeへと渡してください。

実行ステージの詳細についてはタスクシステムの実行ステージを参照してください。

バージョン情報

MGL 1.0.0

• 初回リリース

関連

• StageSettingsArray

• InitializeDescriptor

• MGL::Task::Initialize

---

InitializeDescriptor

初期化記述子

宣言

namespace MGL::Task
{
    struct InitializeDescriptor
    {
        StageSettingsArray stageSettings;
        int32_t parallelExecuteCount;

        InitializeDescriptor() noexcept;
    };
}

説明

タスクシステムを初期化する際に、設定の記述に使用するための構造体です。この記述子をMGL::Task::Initializeの引数に渡すことによってタスクシステムが初期化されます。

各メンバの内容は次の通りです。

MGL::Task::StageSettingsArray stageSettings

各実行ステージの設定を格納した配列です。

実行ステージはこの配列に格納された順に実行されます。

int32_t parallelExecuteCount

タスクの並列実行を利用する際に、同時に実行可能なタスクの数を表す値です。

この値に2以上を設定して渡すことによって、タスクシステムはその数に応じたスレッドプールを内部に構築して使用します。1以下の値を指定した場合はスレッドプールを構築せず、ExecuteModeにParallelizableUpdateを設定した実行ステージはNormalUpdateと同等に扱われます。

生成可能なスレッドの数はシステムによって異なり、同時に実行可能なスレッド数の上限もプロセッサによって異なります。MGL::Task::Initializeはここで指定した数のスレッドの生成を試みますが、実際に生成されるスレッドはそれよりも少なくなる場合があります。また、生成したスレッド全てが同時に実行される保証もない点にご注意ください。

---

kExecuteStageMax

実行ステージの最大数

宣言

namespace MGL::Task
{
    constexpr ExecuteStage kExecuteStageMax = 31;
}

説明

実行ステージとして設定できる値の最大値を表す定数です。

注釈

この値は実行ステージを32ビットのビットフラグで管理できるように31に設定されています。

バージョン情報

MGL 1.0.0

• 初回リリース

関連

• ExecuteStage

• MGL::Task::Initialize