MGL::Task::Node#

概要#

MGL::Task::Nodeはタスクシステムに登録可能なタスクノードの基底クラスです。

このクラスの具体的な利用方法についてはタスクシステムを参照してください。本項では主に各々の関数の仕様についてを解説しています。

宣言#

namespace MGL::Task
{
    class Node;
}

メンバ情報#

種類	名前	内容	バージョン
関数	コンストラクタ		1.0.0+
関数	GetIdentifier	タスクの識別子を取得	1.0.0+
関数	Kill	削除要求	1.0.0+
関数	IsRequestedKill	削除要求を受けているかを取得	1.0.0+
関数	SetResideLevel	常駐レベルを設定	1.1.0+
関数	GetResideLevel	常駐レベルを取得	1.1.0+
関数	IsResident	このタスクが常駐タスクであるかを取得	1.0.0+
関数	SetAsynchronous	並列実行の有効・無効を設定	1.1.11+
関数	IsEnabledAsynchronous	並列実行が有効化されているかを取得	1.1.11+
関数	GetBarrierIdentifier	並列実行時のバリアIDを取得	1.1.11+
関数	IsEnabledBarrier	並列実行時にバリアIDによる終了待ちを行うかを取得	1.1.11+
仮想関数	OnInitialize	タスク初期化時のコールバック関数	1.0.0+
純粋仮想関数	OnExecute	タスク実行時のコールバック関数	1.0.0+
仮想関数	OnReceiveTaskEvent	タスクがイベント通知を受けた際のコールバック関数	1.0.0+
関数	NotifyEvent	タスクへのイベント通知	1.1.11+

コンストラクタ#

宣言#

namespace MGL::Task
{
    class Node
    {
        constexpr Node(Identifier identifier) noexcept;
    };
}

引数#

MGL::Task::Identifier identifier: 生成するタスクの識別子

説明#

タスクノードを初期化するためのコンストラクタです。この関数の引数にタスクIDを指定することによって、タスクノードとタスクIDを関連付けます。

このコンストラクタは通常、アプリケーションごとに使用するタスクノードの基底クラスで呼び出すように実装します。その具体的な実装例はタスクシステムの独自タスクノードの実装例を参照してください。

利用例#

タスクシステムの独自タスクノードの実装例にて詳細の解説と共に実装例を紹介していますので、こちらを参照してください。

バージョン情報#

MGL 1.0.0

初回リリース

GetIdentifier#

タスクの識別子を取得

宣言#

namespace MGL::Task
{
    class Node
    {
        [[nodiscard]] constexpr Identifier GetIdentifier() const noexcept;
    };
}

戻り値#

MGL::Task::Identifier: このタスクの識別子

説明#

このタスクノードに割り当てられているタスクIDを取得します。

この関数は主にタスクシステム内部が管理するために用意されています。通常、この関数を外部から呼び出す機会はありません。

利用例#

// MGL::Task::Node::OnInitialize() から呼び出す例
void AnyTask::OnInitialize() noexcept
{
    MGL_TRACE("タスクID: %d", GetIdentifier());
}

バージョン情報#

MGL 1.0.0

初回リリース

MGL 1.1.13

関数の戻り値に[[nodiscard]]属性を付与

Kill#

タスクの削除要求

宣言#

namespace MGL::Task
{
    class Node
    {
        constexpr void Kill() noexcept;
    };
}

説明#

自身のタスクに対して削除要求を行います。

この関数は自身の削除を目的としているため、MGL::Task::Killとは異なり常駐レベルの評価を行いません。外部からこの関数を直接呼び出すことは推奨されず、代わりにMGL::Task::WeakNode::Killを使用してください。

タスクの削除の詳細についてはタスクシステムのタスクの削除および常駐レベルを参照してください。

利用例#

// 更新処理内でEscキーを押したら削除する例
void AnyTask::OnUpdate() noexcept
{
    MGL::Input::Keyboard keyboard;

    // Escキーを押したら削除
    if (keyboard.IsTriggerd(MGL::Input::Keycode::Escape))
    {
        Kill();     // 自身の削除は常駐レベルに関わらず実行される
    }
}

バージョン情報#

MGL 1.0.0

初回リリース

IsRequestedKill#

タスクが削除要求を受けているかを取得

宣言#

namespace MGL::Task
{
    class Node
    {
        [[nodiscard]] constexpr bool IsRequestedKill() const noexcept;
    };
}

戻り値#

bool: 削除要求を受けている場合はtrue

説明#

このタスクが削除要求を受けているかを取得します。

KillやMGL::Task::Kill、MGL::Task::WeakNode::Killなどで削除要求を受けたタスクは即時削除は行われず、タスクシステムが安全に削除できるタイミングまで削除が保留されます。削除要求を受けてから実際に削除されるまでの間はこの関数の戻り値がtrueとなります。

この関数は主にタスクシステム内部での管理用に使用されています。

利用例#

// 更新処理内で削除要求を受けているかを判別する例
void AnyTask::OnUpdate() noexcept
{
    if (IsRequestedKill())
    {
        MGL_TRACE("削除要求を受けている");
    }
    else
    {
        MGL_TRACE("削除要求は受けていない");
    }
}

バージョン情報#

MGL 1.0.0

初回リリース

MGL 1.1.13

関数の戻り値に[[nodiscard]]属性を付与

SetResideLevel#

常駐レベルを設定

宣言#

namespace MGL::Task
{
    class Node
    {
        constexpr void SetResideLevel(ResideLevel resideLevel) noexcept;
    };
}

引数#

MGL::Task::ResideLevel resideLevel: 設定する常駐レベル

説明#

タスクに常駐レベルを設定します。

常駐レベルはタスクの削除要求の際に評価され、指定された値より大きい常駐レベルが設定されたタスクは削除対象外となります。

より詳しい情報についてはタスクシステムの常駐レベルを参照してください。

利用例#

// 初期化処理中に常駐レベルを Middle(中) に設定する例
void AnyTask::OnInitialize() noexcept
{
    SetResideLevel(MGL::Task::ResideLevel::Middle);
}

バージョン情報#

MGL 1.1.0

初回リリース

補足

MGL 1.0.0ではSetResidentの名前で存在していたが、MGL 1.1.0からは非推奨化、MGL 1.1.11にて削除。

GetResideLevel#

常駐レベルを取得

宣言#

namespace MGL::Task
{
    class Node
    {
        [[nodiscard]] constexpr ResideLevel GetResideLevel() const noexcept;
    };
}

戻り値#

MGL::Task::ResideLevel: 現在設定されている常駐レベル

説明#

SetResideLevelにて設定した常駐レベルを取得します。

常駐レベルに関する詳しい情報についてはタスクシステムの常駐レベルを参照してください。

利用例#

// 更新処理内で現在の常駐レベルを取得
void AnyTask::OnUpdate() noexcept
{
    // 常駐レベルを取得
    auto resideLevel = GetResideLevel();

    switch (resideLevel)
    {
        // NoResident
        case MGL::Task::ResideLevel::Low:
            MGL_TRACE("非常駐");
            break;

        // Low
        case MGL::Task::ResideLevel::Low:
            MGL_TRACE("常駐レベル：低");
            break;

        // Middle
        case MGL::Task::ResideLevel::Middle:
            MGL_TRACE("常駐レベル：中");
            break;

        // High
        case MGL::Task::ResideLevel::High:
            MGL_TRACE("常駐レベル：高");
            break;

        // Max
        case MGL::Task::ResideLevel::Max:
            MGL_TRACE("常駐レベル：最大");
            break;
    }
}

バージョン情報#

MGL 1.1.0

初回リリース

MGL 1.1.13

関数の戻り値に[[nodiscard]]属性を付与

IsResident#

このタスクが常駐タスクであるかを取得

宣言#

namespace MGL::Task
{
    class Node
    {
        [[nodiscard]] constexpr bool IsResident() const noexcept;
    };
}

戻り値#

bool: 常駐レベルがMGL::Task::ResideLevel::NoResidentの場合はfalse、それ以外の常駐レベルが設定されている場合はtrue

説明#

このタスクに常駐レベルが設定されているかを取得します。この関数の戻り値はGetResideLevel() != MGL::Task::ResideLevel::NoResidentと等価となります。

常駐レベルに関する詳しい情報についてはタスクシステムの常駐レベルを参照してください。

利用例#

// 更新処理内で常駐タスクかどうかを判別する例
void AnyTask::OnUpdate() noexcept
{
    if (IsResident())
    {
        MGL_TRACE("このタスクは常駐タスク");
    }
    else
    {
        MGL_TRACE("このタスクは非常駐タスク");
    }
}

バージョン情報#

MGL 1.0.0

初回リリース

MGL 1.1.13

関数の戻り値に[[nodiscard]]属性を付与

SetAsynchronous#

並列実行の有効・無効を設定

宣言#

namespace MGL::Task
{
    class Node
    {
        constexpr void SetAsynchronous(
            bool isEnabled,
            Identifier barrierIdentifier = 0) noexcept;
    };
}

引数#

bool isEnabled: trueを指定すると有効化、falseで無効化
MGL::Task::Identifier barrierIdentifier: 実行完了の待ち合わせを行うタスクの識別子。省略時は0（無効化）

説明#

並列実行可能な実行ステージにおける、タスクの非同期設定を行う関数です。

isEnabledにtrueを設定した場合、並列実行可能な実行ステージににおいて更新処理を非同期に実行するようになります。デフォルトではfalseが設定されており、並列実行は無効化されています。

barrierIdentifierには非同時に実行される更新処理の待ち合わせを行うタスクIDを指定します。この引数にタスクIDを指定することで、そのタスクの実行前に必ず同期を取るようになり、以降のタスクからは安全にアクセス可能になります。

barrierIdentifierを省略、または自身のタスクIDより小さな値を指定した場合、更新処理の同期は実行ステージの最後に行われます。

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

利用例#

// 初期化処理内で並列実行を有効化する例
void AnyTask::OnInitialize() noexcept
{
    // 並列実行を有効化し、プレイヤータスク実行前までに完了させる例
    SetAsynchronous(true, TaskID::Player);
}

バージョン情報#

MGL 1.1.11

初回リリース

IsEnabledAsynchronous#

並列実行が有効化されているかを取得

宣言#

namespace MGL::Task
{
    class Node
    {
        [[nodiscard]] constexpr bool IsEnabledAsynchronous() const noexcept;
    };
}

戻り値#

bool: 並列実行が有効化されている場合はtrue、無効な場合はfalse

説明#

タスクの並列実行が有効化な設定になっているかを取得します。

この関数はSetAsynchronousの引数isEnabledに設定した値をそのまま返します。並列実行ができない環境下においても、タスク自身に有効化設定を行っている場合はtrueを返す点にご注意ください。

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

利用例#

// 更新処理内で並列実行か有効化されているかを判別する例
void AnyTask::OnUpdate() noexcept
{
    if (IsEnabledAsynchronous())
    {
        MGL_TRACE("このタスクは並列実行が有効化されている");
    }
    else
    {
        MGL_TRACE("このタスクは並列実行が有効化されていない");
    }
}

バージョン情報#

MGL 1.1.11

初回リリース

MGL 1.1.13

関数の戻り値に[[nodiscard]]属性を付与

GetBarrierIdentifier#

並列実行時のバリアIDを取得

宣言#

namespace MGL::Task
{
    class Node
    {
        [[nodiscard]] constexpr Identifier GetBarrierIdentifier() const noexcept;
    };
}

戻り値#

MGL::Task::Identifier: 終了待ちを行うタスクの識別子

説明#

タスクの並列実行時のバリアIDを取得します。この関数はSetAsynchronousの引数barrierIdentifierに設定した値をそのまま返します。

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

利用例#

// 更新処理内で並列実行か有効化されているかを判別する例
void AnyTask::OnUpdate() noexcept
{
    MGL_TRACE("バリアID：%d\n", GetBarrierIdentifier());
}

バージョン情報#

MGL 1.1.11

初回リリース

MGL 1.1.13

関数の戻り値に[[nodiscard]]属性を付与

IsEnabledBarrier#

並列実行時にバリアIDによる終了待ちを行うかを取得

宣言#

namespace MGL::Task
{
    class Node
    {
        [[nodiscard]] constexpr bool IsEnabledBarrier() const noexcept;
    };
}

戻り値#

bool: 有効なバリアIDが設定されている場合はtrue

説明#

タスクの並列実行時のバリアIDに有効な値が設定されているかを取得します。

自身のタスクIDよりも大きなバリアIDが設定されている場合、この関数はtrueを返し、そのタスクが実行される前に待ち合わせを行います。この関数がfalseを返すタスクは有効なバリアIDが設定されておらず、更新処理の待ち合わせは実行ステージの最後に行われます。

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

利用例#

// 更新処理内で有効なバリアIDが設定されているかを取得する例
void AnyTask::OnUpdate() noexcept
{
    if (IsEnabledBarrier())
    {
        MGL_TRACE("このタスクはバリアIDによる同期を行う");
    }
    else
    {
        MGL_TRACE("このタスクは実行ステージの最後に同期を行う");
    }
}

バージョン情報#

MGL 1.1.11

初回リリース

MGL 1.1.13

関数の戻り値に[[nodiscard]]属性を付与

OnInitialize#

タスク初期化時のコールバック関数

宣言#

namespace MGL::Task
{
    class Node
    {
        virtual void OnInitialize() noexcept;
    };
}

説明#

MGL::Task::Createによるタスク生成が行われた後、1度だけ呼び出される関数です。

この関数が呼び出されるタイミングはコンストラクタの呼び出し直後となります。何らかの理由でコンストラクタでの記述を避けたい初期化処理などはこちらを使用してください。

この関数の詳しい利用例はタスクシステムにて複数解説しているため、こちらも併せて参照してください。

利用例#

class AnyTask : public MGL::Task::Node
{
    //  ... 省略

    virtual void OnInitialize() noexcept override
    {
        // コンストラクタ呼び出し直後にこの関数が呼び出される
    }
}

バージョン情報#

MGL 1.0.0

初回リリース

OnExecute#

タスク実行時のコールバック関数

宣言#

namespace MGL::Task
{
    class Node
    {
        virtual void OnExecute(ExecuteStage stage) noexcept = 0;
    };
}

引数#

MGL::Task::ExecuteStage stage: 現在の実行ステージを表す識別子

説明#

タスク実行時に呼び出されるコールバック関数です。

この関数は1回のMGL::Task::Executeの呼び出しに対し、登録されている実行ステージの回数だけ呼び出しが行われます。引数stageは現在の実行ステージを表す値が渡されます。

この関数の継承は、アプリケーションごとに定義するタスクノードの基底クラス側で処理することを想定しています。デフォルトタスクノードを使用する場合、この関数を意識する必要はありません。

実行ステージやこの関数の具体的な利用例についてはタスクシステムのタスクノードのカスタマイズを参照してください。

利用例#

タスクシステムのタスクノードのカスタマイズにてより具体的な解説を行なっているため、こちらを参照してください。

バージョン情報#

MGL 1.0.0

初回リリース

OnReceiveTaskEvent#

タスクがイベント通知を受けた際のコールバック関数

宣言#

namespace MGL::Task
{
    class Node
    {
    protected:
        virtual void OnReceiveTaskEvent(
            EventIdentifier eventID,
            void *argument) noexcept;
    };
}

引数#

MGL::Task::EventIdentifier eventID: イベントの種類を表す識別子
void *argument: イベントの通知元から渡される引数

説明#

タスクがイベント通知を受けた際に呼び出されるコールバック関数です。

MGL::Task::NotifyEventやMGL::Task::WeakNode::NotifyEventが呼び出された際、対象となったタスクのこのコールバック関数が呼び出されます。引数のeventIDおよびargumentには、呼び出し元で指定した両者の値がそのまま渡されます。

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

利用例#

タスクシステムのイベント通知にて、呼び出し元も含めた詳しい解説を行なっているため、こちらを参照してください。

バージョン情報#

MGL 1.0.0

初回リリース

MGL 1.1.11

privateへと移行し、外部からはNotifyEventを経由するように変更

NotifyEvent#

タスクへのイベント通知

宣言#

namespace MGL::Task
{
    class Node
    {
        template <typename EventIDType>
        void NotifyEvent(EventIDType event, void *argument) noexcept;
    };
}

テンプレート引数#

EventIDType: イベントの種類を表す任意の型

引数#

EventIDType event: イベントの種類を表す識別子
void *argument: 通知先のタスクに渡す引数

説明#

このタスクに対してイベント通知を行います。

指定された2つの引数を使用してOnReceiveTaskEventを呼び出します。

この関数はアプリケーション側で定義したイベントIDの型を解決できるよう、テンプレート関数となっています。通常、テンプレート引数は第1引数の型から推論されるため、明示的に指定する必要はありません。

イベント通知は外部から呼び出されることを想定していますが、弱参照ノードもイベント通知を行うMGL::Task::WeakNode::NotifyEventを持っています。特別な理由がない限り、この関数を直接呼び出す必要はありません。

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

利用例#

// ポーズイベントを通知
if (auto node = weakNode.Get(); node != nullptr)
{
    node->NotifyEvent(EventID::Pause);
}

// 特別な理由がない限り、次のように弱参照ノードが持つ関数の使用を推奨 （効果は上記と同等）
weakNode.NotifyEvent(EventID::Pause);

バージョン情報#

MGL 1.1.11

初回リリース

MGLドキュメント

MGL::Task::Node

Contents

MGL::Task::Node#

概要#

宣言#

メンバ情報#

コンストラクタ#

宣言#

引数#

説明#

利用例#

バージョン情報#

関連#

GetIdentifier#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

関連#

Kill#

宣言#

説明#

利用例#

バージョン情報#

関連#

IsRequestedKill#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

関連#

SetResideLevel#

宣言#

引数#

説明#

利用例#

バージョン情報#

関連#

GetResideLevel#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

関連#

IsResident#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

関連#

SetAsynchronous#

宣言#

引数#

説明#

利用例#

バージョン情報#

関連#

IsEnabledAsynchronous#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

関連#

GetBarrierIdentifier#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

関連#

IsEnabledBarrier#

宣言#

戻り値#

説明#