遅延イベントキュー

危険な場所ではイベントをキューに入れ、自分で選んだ安全なポイントでバッチ全体を順序どおりにパブリッシュします。

概要

遅延イベントキューは、イベントバス(IEventBus)の上に載る薄い層です。イベントを即座にパブリッシュする代わりに Enqueue します。キューは Flush() を呼ぶまですべてを保持し、Flush() がバッチ全体をイベントバス経由でパブリッシュします — すべてのイベント型を横断して、キューに入れられた正確な順序で。

イベントのパブリッシュを危険な場所 — 物理コールバック、変更中でもあるコレクションへのループ、入力処理の途中 — から、自分で選んだ安全なポイントへ移すために使います。キューが所有するのは保持と順序だけです。ルーティングと購読者の処理はイベントバスに残ります。自動フラッシュはありません：バッチをいつ発火するかはあなたが決めます。メインスレッド専用です。

クイックスタート

イベントをプレーンなクラスとして定義します：

public sealed class EnemyDiedEvent
{
    public int EnemyId { get; }
    public EnemyDiedEvent(int enemyId) { EnemyId = enemyId; }
}

そして今キューに入れ、後でパブリッシュします：

using CommonGameSystem.Core;
using UnityEngine;

public class MyDeferredPublisher : MonoBehaviour
{
    private IDeferredBus _bus;

    private void Awake() => _bus = ServiceLocator.Resolve<IDeferredBus>();

    public void OnEnemyDied(int enemyId)
    {
        _bus.Enqueue(new EnemyDiedEvent(enemyId));   // queued — NOT published yet
    }

    private void LateUpdate()
    {
        _bus.Flush();   // publishes the batch through the Event Bus, in queue order
    }
}

Bootstrap は起動時にこのサービスを自動登録します。上のように、Awake() で一度解決してキャッシュしてください。

API リファレンス

IDeferredBus

DeferredBusOptions — 構築時の readonly struct

使用例

using CommonGameSystem.Core;
using UnityEngine;

public sealed class DamageDealtEvent
{
    public int EnemyId { get; }
    public int Amount { get; }
    public DamageDealtEvent(int enemyId, int amount) { EnemyId = enemyId; Amount = amount; }
}

public class DamageResolver : MonoBehaviour
{
    private IDeferredBus _deferred;

    private void Awake() => _deferred = ServiceLocator.Resolve<IDeferredBus>();

    // Called from inside a physics callback — publishing immediately here could
    // re-enter the collection we are iterating. Queue it instead.
    public void OnHit(int enemyId, int amount)
    {
        _deferred.Enqueue(new DamageDealtEvent(enemyId, amount));
    }

    // Publish at a known-safe point: the end of the fixed-update step.
    private void FixedUpdate()
    {
        if (_deferred.PendingCount > 0)
            _deferred.Flush();   // every queued event publishes here, in queue order
    }
}

無効化する

ServiceLocator.Replace<IDeferredBus>(new NullDeferredBus());

これで遅延処理が完全にミュートされます。Enqueue はイベントを静かに捨て(実際のバスへ再ルーティングされることはありません)、Flush は何もせず、PendingCount は 0 のままです。実際の遅延キューに対して配線されたゲームは、遅延処理オフのまま動き続けます。イベントバスの無音な NullEventBus と異なり、この置き換えは構築時に 1 回警告をログします。静かに捨てるキュー(「イベントはキューされているようだが決して届かない」)は診断が難しいため、誤った差し替えを可視化しています。null イベントは、本物のサービスとまったく同じく引き続き例外を投げます。

よくある落とし穴

• Flush するまで何も発火しません。 自動フラッシュはありません。キューに入れてフラッシュしなければ、イベントは決してパブリッシュされず、PendingCount は際限なく増えます。予測可能なドレインポイントを 1 つ — FixedUpdate の最後、フレームの最後 — 選び、必ずそこでフラッシュしてください。
• フラッシュ中にキューされたイベントは、次のフラッシュを待ちます。 バッチは Flush が始まった瞬間に確定します。バッチのパブリッシュ中に購読者がエンキューしたものは、次の Flush まで保持されます。これは意図的です：どの 1 回のフラッシュも有界に保たれます。
• MaxDrainPerFlush はバッチを分割します — イベントを捨てることはありません。 上限に達すると、残ったイベントは次のバッチの先頭へ移るので、後からキューされたものより先にパブリッシュされます。順序は保たれ、スロットルされた警告が 1 回ログされます。これは圧力弁であって、破棄ではありません。
• フラッシュは決して例外を投げず、1 つの不良イベントが残りを止めることはできません。 Publish 呼び出しが例外を投げると、キューはそれを捕捉してログし、残りのイベントで続行します。フレームワーク自身のイベントバスは、欠陥のある購読者をすでに自分で隔離します。このガードは、そうしない置き換えバスをカバーするためのものです。

関連ページ

• イベントバス — このキューがパブリッシュに使うルーティング層
• スケジューラー — フラッシュポイントではなく、選んだ時刻に後からコールバックを実行する
• ロガー — フラッシュの障害とライフサイクルトレースの行き先