MGL::Task::WeakNode#

概要#

MGL::Task::WeakNodeはタスクの弱参照ノードを表すクラスです。

タスクノードは頻繁に削除や生成が繰り返されるため、一般的なポインタ変数や参照で安全に保持することができません。この弱参照ノードを使用することによって、参照先のタスクが有効であるかを検知し、外部から安全にタスクノードへとアクセス可能になります。

弱参照ノードの取り扱い方法についてはタスクシステムのタスクの参照を参照してください。

宣言#

namespace MGL::Task
{
    class WeakNode;
}

メンバ情報#

種類

名前

内容

バージョン

関数

コンストラクタ

1.0.0+

関数

Set

参照先のタスクノードの設定

1.0.0+

関数

Get

参照先のタスクノードを取得

1.0.0+

関数

IsValid

参照先の有効状態を取得

1.1.11+

関数

NotifyEvent

イベント通知

1.1.11+

関数

Kill

削除要求

1.1.11+

関数

operator bool

bool型へのキャスト

1.1.11+

関数

operator !

否定演算子のオペレータ

1.1.11+

コンストラクタ#

宣言#

namespace MGL::Task
{
    class WeakNode
    {
        // (1) 空の弱参照ノードを生成
        constexpr WeakNode() noexcept;

        // (2) タスクノードを指定して初期化
        WeakNode(const Node *node) noexcept;

        // (3) ノードリスト上のインデックスを指定して初期化
        WeakNode(size_t listIndex) noexcept;
    };
}

引数#

(1) 空の弱参照ノードを生成

引数なし

(2) タスクノードを指定して初期化
const MGL::Task::Node *node

参照先のタスクノード

(3) ノードリスト上のインデックスを指定して初期化
size_t listIndex

ノードリスト上のインデックス

説明#

タスクの弱参照ノードを生成するためのコンストラクタです。

(1)は何も参照しない空の弱参照ノードを生成します。空の弱参照ノードは主に無効なノードの表現に利用されます。

(2)はタスクノードのアドレスを指定して初期化を行います。引数に指定するアドレスは必ずその時点で有効なタスクノードを指定しなければなりません。

(3)はタスクシステム内部で弱参照ノードを生成する場合のみに利用されます。アプリケーション側からはこの呼び出しを利用できる機会はありません。

注釈

初期値として空の弱参照ノードを生成する場合を除き、通常はアプリケーション側から弱参照ノードを生成する必要はありません。MGL::Task::CreateやMGL::Task::Findの戻り値を使用してください。

利用例#

// (1) 空の弱参照ノードを生成
MGL::Task::WeakNode emptyWeakNode();

// (2) タスクノードを指定して初期化（下記の注釈も参照）
MGL::Task::WeakNode thisWeakNode(this);     // 自身の弱参照ノードを生成する例

// (3) ノードリスト上のインデックスを指定して初期化
// アプリケーション側から使用できないため省略

注釈

アドレスからの弱参照ノードの生成は、アプリケーション側からは自分自身の弱参照ノードを生成する以外に使用する機会がありません。外部からは必ず弱参照ノードを経由しなければタスクノードのアドレスを取得できないためです。

バージョン情報#

MGL 1.0.0

  • 初回リリース

関連#

Set#

参照先のタスクノードの設定

宣言#

namespace MGL::Task
{
    class WeakNode
    {
        // (1) タスクノードを指定して設定
        bool Set(const Node *node) noexcept;

        // (2) ノードリスト上のインデックスを指定して設定
        bool Set(size_t listIndex) noexcept;
    };
}

引数#

(1) タスクノードを指定して設定
const MGL::Task::Node *node

参照先のタスクノード

(2) ノードリスト上のインデックスを指定して設定
size_t listIndex

ノードリスト上のインデックス

戻り値#

成功時にtrue、失敗時にfalse

説明#

弱参照ノードに参照先を設定します。

この関数はコンストラクタに同様の引数を指定した場合と同じ動作を行います。詳細はコンストラクタを参照してください。

利用例#

コンストラクタを参照してください。

バージョン情報#

MGL 1.0.0

  • 初回リリース

関連#

Get#

参照先のタスクノードを取得

宣言#

namespace MGL::Task
{
    class WeakNode
    {
        // (1) MGL::Task::Node型で取得
        [[nodiscard]] Node *Get() const noexcept;

        // (2) 指定した型にキャストして取得
        template <class T, Identifier identifier = Identifier(T::kTaskIdentifier)>
        [[nodiscard]] T *Get() const noexcept;
    };
}

テンプレート引数#

(1) MGL::Task::Node型で取得

テンプレート引数なし

(2) 指定した型にキャストして取得
class T

変換先のタスクノードクラスの型

Identifier identifier

そのクラスに関連付けられているタスクID。Tに指定した型がstaticな公開メンバkTaskIdentifierを持つ場合は省略可能

戻り値#

(1) MGL::Task::Node型で取得
MGL::Task::Node *

参照先が有効である場合はそのタスクノードのアドレス、参照先が無効な場合はnullptr

(2) 指定した型にキャストして取得
T *

正しく変換できた場合はそのタスクノードのアドレス。失敗した場合はnullptr

説明#

参照先のタスクが有効な場合、そのタスクノードのアドレスを取得します。

(1)はMGL::Task::Node型で取得し、(2)はテンプレート引数で指定した型にキャストして取得します。

(2)のテンプレート引数のTには変換先のタスクノードの型を、identifierにはそのタスクノードに関連付けられたタスクIDを指定します。もしTに指定した型が自身のタスクIDを表すstaticな公開メンバ変数としてkTaskIdentifierを持っている場合、テンプレート引数のidentifierは省略可能です。

取得に成功した場合、引数weakNodeの参照先タスクノードのアドレスが返ります。参照先タスクノードが既に削除要求を受けている場合や、キャストに失敗した場合はnullptrが返ります。

利用例#

// 敵タスクの生存状態を取得する関数の例
// ここでは敵タスク EnemyTask が生存状態 IsAlive() を持っているとする
bool IsAliveEnemy(MGL::Task::WeakNode enemyTask) noexcept
{
    // ノードキャストによって敵タスクのタスクノードを取得
    auto enemy = enemyTask.Get<EnemyTask>();

    // enemyTask が敵タスクを参照していない、
    // または参照先の敵タスクが既に削除されている場合は nullptr となる。
    // ここでは生存していないものとみなして false を返す。
    if (enemy == nullptr)
    {
        return false;
    }

    // enemy の取得に成功した場合は EnemyTask のメンバ関数を呼び出し
    return enemy->IsAlive();
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

MGL 1.1.11

  • MGL::Task::NodeCastの廃止に伴い(2)を新たに導入

MGL 1.1.13

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

関連#

IsValid#

参照先の有効状態を取得

宣言#

namespace MGL::Task
{
    class WeakNode
    {
        bool IsValid() const noexcept;
    };
}

戻り値#

参照先が有効である場合はtrue、無効な場合はfalse

説明#

参照先が有効であるかを取得します。

参照先のタスクノードがタスクシステム上に登録されており、削除要求も受けていない場合はtrueが返ります。参照先が空であったり、既に削除されている場合はfalseが返ります。

この関数がfalseを返す場合、Getはnullptrを返し、参照先のタスクノードを取得することはできません。

この関数はoperator boolやoperator !での代用も可能です。

利用例#

// タスク AnyTask を生成
auto weakNode = MGL::Task::Create<AnyTask>();

// IsValid() を用いて生成に成功しているかをチェック
if (weakNode.IsValid())
{
    /*
     *  生成に成功している場合はここに到達
     */


    // 参照先のタスクを削除
    weakNode.Kill();

    if (weakNode.IsValid())
    {
        // 上記の削除要求を受けたため、もうここには到達しない
    }
}
else
{
    // 生成に失敗している場合はここに到達
}

バージョン情報#

MGL 1.1.11

  • 初回リリース

関連#

NotifyEvent#

イベント通知

宣言#

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

テンプレート引数#

EventIDType

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

引数#

EventIDType event

イベントの種類を表す識別子

void *argument

通知先のタスクに渡す引数

戻り値#

bool

成功時にtrue、参照先が無効だった場合にfalse

説明#

参照先のタスクノードに対してイベント通知を行います。

引数に指定したeventとargumentを用いて、参照先タスクのMGL::Task::Node::OnReceiveTaskEventを呼び出します。参照先が無効である場合は呼び出しを行わず、戻り値としてfalseを返します。

イベント通知の詳細についてはタスクシステムのイベント通知を参照してください。

利用例#

// タスクとして登録されている全ての敵を取得 (TaskID::Enemyを敵タスクと仮定）
auto enemies = MGL::Task::Find(TaskID::Enemy);

// 全ての敵タスクに対してポーズを通知
for (auto enemy : enemies)
{
    enemy.NotifyEvent(TaskEvent::Pause);
}


// Note: 上記の処理は次の記述と等価
MGL::Task::NotifyEvent(TaskID::EnemyTask, TaskEvent::Pause);

バージョン情報#

MGL 1.1.11

  • 初回リリース

関連#

Kill#

削除要求

宣言#

namespace MGL::Task
{
    class WeakNode
    {
        bool Kill(ResideLevel resideLevel = ResideLevel::NoResident) noexcept;
    };
}

引数#

MGL::Task::ResideLevel resideLevel

削除対象となる常駐レベル

戻り値#

bool

成功時にtrue、失敗時にfalse

説明#

参照先のタスクノードに対して削除要求を行います。

引数には削除対象となる常駐レベルを指定した場合、この値とタスクに設定された常駐レベルを比較し、引数以下の場合にのみ削除要求を行います。省略時は常駐レベルが設定されていない場合にのみ削除要求を行います。

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

参照先のタスクノードに削除要求を行えた場合は戻り値にtrueが返ります。参照先が無効だったり、常駐レベルの設定により削除要求が行えなかった場合は戻り値がfalseとなります。

利用例#

// タスクとして登録されている全ての敵を取得 (TaskID::Enemyを敵タスクと仮定）
auto enemies = MGL::Task::Find(TaskID::Enemy);

// 全ての敵タスクに対して削除要求
for (auto enemy : enemies)
{
    enemy.Kill();
}


// Note: 上記の処理は次の記述と等価
MGL::Task::Kill(TaskID::EnemyTask);

バージョン情報#

MGL 1.1.11

  • 初回リリース

関連#

operator bool#

bool型へのキャスト

宣言#

namespace MGL::Task
{
    class WeakNode
    {
        explicit operator bool() const noexcept;
    };
}

戻り値#

参照先が有効である場合はtrue、無効な場合はfalse

説明#

IsValidをbool型へのキャストで代用するためのオペレータです。

利用例#

// タスク AnyTask を生成
auto weakNode = MGL::Task::Create<AnyTask>();
if (weakNode)
{
    // 生成に成功している場合はここに到達
}

バージョン情報#

MGL 1.1.11

  • 初回リリース

関連#

operator !#

否定演算子のオペレータ

宣言#

namespace MGL::Task
{
    class WeakNode
    {
        bool operator!() const noexcept;
    };
}

戻り値#

参照先が有効である場合はfalse、無効な場合はtrue

説明#

参照先が無効であるかを!演算子で取得するためのオペレータです。この戻り値は!IsValid()と等価です。

利用例#

// タスク AnyTask を生成
auto weakNode = MGL::Task::Create<AnyTask>();
if (!weakNode)
{
    // 生成に失敗している場合はここに到達
}

バージョン情報#

MGL 1.1.11

  • 初回リリース

関連#