Unityのコルーチンの分解、或いはUniRxのMainThreadDispatcherについて

この記事はUnity Advent Calendar 2014のための記事になります。昨日はkomiyakさんのUnity を使いはじめたばかりの頃の自分に伝えたい、Unity の基本 【2014年版】でした。いやー、これはまとまってて嬉しい情報です。ところでカレンダー的には穴開けちゃってます（遅刻遅延！）、すみません……。

さて、今回の内容ですが、私の作っているUniRxというReactive Programming（バズワード of 2014！)のためのライブラリを、最近ありがたいことに結構使ってみたーという声を聞くので、Rxの世界とUnityの世界を繋ぐ根幹である、MainThreadDispatcherと、その前準備に必要なコルーチンについて書きます。

Coroutine Revisited

コルーチンとはなんぞや。なんて今更ですって！はい。とりあえず、Unityは基本的にシングルスレッドで動いています。少なくともスクリプト部分に関しては。Unityのコルーチンは、IEnumeratorでyield returnすると、その次の処理を次フレーム（もしくは一定秒数/完了後などなど）に回します。あくまでシングルスレッド、ということですね。挙動について。簡単な確認用スクリプトを貼っつけて見てみると……

void Start()
{
    Debug.Log("begin-start:" + Time.frameCount);
    StartCoroutine(MyCoroutine());
    Debug.Log("end-start" + Time.frameCount);
}

IEnumerator MyCoroutine()
{
    Debug.Log("start-coroutine:" + Time.frameCount);

    yield return null;
    Debug.Log("after-yield-null:" + Time.frameCount);

    yield return new WaitForSeconds(3);
    Debug.Log("end-coroutine:" + Time.frameCount);
}

呼ばれる順番とframeCountを考えてみようクイズ！意外と引っかかるかもしれません。答えのほうですが……

begin-start:1
start-coroutine:1
end-start:1
after-yield-null:2
end-coroutine:168

となります。最後の秒数のフレームカウントはどうでもいいとして、start-coroutineが呼ばれるのはend-startの前ってのがちょっとだけヘーってとこかしら。IEnumerator自体はUnity固有の機能でもなく、むしろC#の標準機能で、通常は戻り値を持ってイテレータを生成するのに使います（Pythonでいうところのジェネレータ）

// 偶数のシーケンスを生成
IEnumerable<int> EvenSequence(int from, int to)
{
    for (int i = from; i <= to; i++)
    {
        if (i % 2 == 0)
        {
            yield return i;
        }
    }
}

void Run()
{
    var seq = EvenSequence(1, 10);

    // シーケンスはforeachで消費可能
    foreach (var item in seq)
    {
        Debug.Log(item);
    }

    // あるいはEnumeratorを取得し回す(foreachは↓のコードを生成する)
    // Unityでのコルーチンでの利用され方はこっちのイメージのほうが近い
    using (var e = seq.GetEnumerator())
    {
        while (e.MoveNext())
        {
            Debug.Log(e.Current);
        }
    }
}

Unityのコルーチンとしてのイテレータの活用法は、戻り値を原則使わず(宣言がIEnumerator)、yield returnとyield returnの間に副作用を起こすために使うということですね。これはこれで中々ナイスアイディアだとは思ってます。

言語システムとしてはC#そのままなので、誰かがIEnumeratorを消費しているということになります。もちろん、それはStartCoroutineで、呼んだ瞬間にまずはMoveNext、その後はUpdateに相当するようなタイミングで毎フレームMoveNextを呼び続けているようなイメージ。

擬似的にMonoBehaviourで再現すると

public class CoroutineConsumer : MonoBehaviour
{
    public IEnumerator TargetCoroutine; // 何か外からセットしといて

    void Update()
    {
        if (TargetCoroutine.MoveNext())
        {
            var current = TargetCoroutine.Current;
            // 基本的にCurrent自体はそんな意味を持たないで次フレームに回すだけ
            if (current == null)
            {
                // next frame
            }
            // ただしもし固有の何かが返された時はちょっとした別の挙動する
            if (current is WaitForSeconds)
            {
                // なんか適当に秒数待つ（ThreadをSleepするんじゃなく挙動的には次フレームへ）
            }
            else if (current is WWW)
            {
                // isDoneになってるまで適当に待つ（ThreadをSleepするんじゃなく挙動的には次フレームへ）
            }
            // 以下略
        }
    }
}

こんな感じでしょうか！yield returnで返す値が具体的にUnityのゲームループにおいてどこに差し込まれるかは、UnityのマニュアルのScript Lifecycle Flowchartの図を見るのが分かりやすい。

nullが先頭でWaitForEndOfFrameは末尾なのね、とか。yield returnで返して意味を持つ値はYieldInstruction、ということになっているはずではあるんですが、実際のとこWWWはYieldInstructionじゃないし、YieldInstruction自体はカスタマイズ不能で自分で書けるわけじゃないんで（イマイチすぎる……）なんだかなぁー。Lifecycle Flowchartに書かれていない中でyield可能なのはAsyncOperationかな？

もしイテレータの挙動について更に詳しく知りたい人は、私の以前書いたスライドAn Internal of LINQ to Objectsの14Pを参照してくださいな。

UniRx.FromCoroutine

というわけかで（一旦）コルーチンの話はおしまい。ここからはUniRxの話。UniRxについてはneue cc - A Beginners Guide to Reactive Extensions with UniRxあたりをどうぞ。UniRxはFromCoroutineメソッドにより、コルーチンをUniRxの基盤インターフェースであるIObservable<T>に変換します。

// こんなのがあるとして
IEnumerator CoroutineA()
{
    Debug.Log("a start");
    yield return new WaitForSeconds(1);
    Debug.Log("a end");
}

// こんなふうに使える
Observable.FromCoroutine(CoroutineA)
    .Subscribe(_ => Debug.Log("complete"));
    
// 戻り値のあるバージョンがあるとして
IEnumerator CoroutineB(IObserver<int> observer)
{
    observer.OnNext(100);
    yield return new WaitForSeconds(2);
    observer.OnNext(200);
    observer.OnCompleted();
}

// こんなふうに合成もできる
var coroutineA = Observable.FromCoroutine(CoroutineA);
var coroutineB = Observable.FromCoroutine<int>(observer => CoroutineB(observer));

// Aが終わった後にBの起動、Subscribeには100, 200が送られてくる
var subscription = coroutineA.SelectMany(coroutineB).Subscribe(x => Debug.Log(x));

// Subscribeの戻り値からDisposeを呼ぶとキャンセル可能
// subscription.Dispose();

IObservable<T>になっていると何がいいかというと、合成可能になるところです。Aが終わった後にBを実行する、Bが失敗したらCを実行する、などなど。また、戻り値を返すことができるようになります。そして、コルーチンに限らず、あらゆるイベント、あらゆる非同期がIObservable<T>になるので、全てをシームレスに繋ぎ合わせることができる。そこが他のライブラリや手法と一線を画すRxの強みなんです、が、長くなるのでここでは触れません:)

また、MonoBehaviour.StartCoroutineを呼ばなくてもコルーチンが起動しています。これは結構大きな利点だと思っていて、というのも、コルーチンを使うためだけにMonoBehaviourにする必要がなくなる。やはり普通のC#クラスのほうが取り回しが良いので、MonoBehaviourにする必要がないものはしないほうがいい。けれど、コルーチンは使いたい。そうした欲求に応えてくれます。

更にFromCoroutine経由にするとEditor内部では通常は動かせないコルーチンを動かすことができます！（これについては後で説明します）

といった応用例はそのうちやるということで、とりあえずFromCoroutineの中身を見て行きましょう。

// Func<IEnumerator>はメソッド宣言的には「IEnumerator Hoge()」になる
public static IObservable<Unit> FromCoroutine(Func<IEnumerator> coroutine, bool publishEveryYield = false)
{
    return FromCoroutine<Unit>((observer, cancellationToken) => WrapEnumerator(coroutine(), observer, cancellationToken, publishEveryYield));
}

// ↑のはWrapEnumeratorを介してこれになっている
public static IObservable<T> FromCoroutine<T>(Func<IObserver<T>, CancellationToken, IEnumerator> coroutine)
{
    return Observable.Create<T>(observer =>
    {
        var cancel = new BooleanDisposable();

        MainThreadDispatcher.SendStartCoroutine(coroutine(observer, new CancellationToken(cancel)));

        return cancel;
    });
}

// WrapEnumeratorの中身は(ｵｪｪｪｪ
static IEnumerator WrapEnumerator(IEnumerator enumerator, IObserver<Unit> observer, CancellationToken cancellationToken, bool publishEveryYield)
{
    var hasNext = default(bool);
    var raisedError = false;
    do
    {
        try
        {
            hasNext = enumerator.MoveNext();
        }
        catch (Exception ex)
        {
            try
            {
                raisedError = true;
                observer.OnError(ex);
            }
            finally
            {
                var d = enumerator as IDisposable;
                if (d != null)
                {
                    d.Dispose();
                }
            }
            yield break;
        }
        if (hasNext && publishEveryYield)
        {
            try
            {
                observer.OnNext(Unit.Default);
            }
            catch
            {
                var d = enumerator as IDisposable;
                if (d != null)
                {
                    d.Dispose();
                }
                throw;
            }
        }
        if (hasNext)
        {
            yield return enumerator.Current; // yield inner YieldInstruction
        }
    } while (hasNext && !cancellationToken.IsCancellationRequested);

    try
    {
        if (!raisedError && !cancellationToken.IsCancellationRequested)
        {
            observer.OnNext(Unit.Default); // last one
            observer.OnCompleted();
        }
    }
    finally
    {
        var d = enumerator as IDisposable;
        if (d != null)
        {
            d.Dispose();
        }
    }
}

WrapEnumeratorの中身が長くてオェェェって感じなんですが何やってるかというと、元のコルーチンを分解して、Rx的に都合のいい形に再構築したコルーチンに変換してます。都合のいい形とは「キャンセル可能」「終了時（もしくは各yield時）にObserver.OnNextを呼ぶ」「全ての完了時にObserver.OnCompletedを呼ぶ」「エラー発生時にObserver.OnErrorを呼ぶ」を満たしているもの。コルーチン自体がC#の標準機能のままで、なにも特別なことをしていないなら、別に自分で回す(enumerator.MoveNextを手で呼ぶ)ことも、何も問題はない、わけです。

そんなラップしたコルーチンを動かしているのがMainThreadDispatcher.SendStartCoroutine。今のMainThreadDispatcher.csは諸事情あって奇々怪々なんですが、SendStartCoroutineのとこだけ取り出すと

public sealed class MainThreadDispatcher : MonoBehaviour
{
    // 中略
    
    /// <summary>ThreadSafe StartCoroutine.</summary>
    public static void SendStartCoroutine(IEnumerator routine)
    {
#if UNITY_EDITOR
        if (!Application.isPlaying) { EditorThreadDispatcher.Instance.PseudoStartCoroutine(routine); return; }
#endif

        if (mainThreadToken != null)
        {
            StartCoroutine(routine);
        }
        else
        {
            Instance.queueWorker.Enqueue(() => Instance.StartCoroutine_Auto(routine));
        }
    }

    new public static Coroutine StartCoroutine(IEnumerator routine)
    {
#if UNITY_EDITOR
        if (!Application.isPlaying) { EditorThreadDispatcher.Instance.PseudoStartCoroutine(routine); return null; }
#endif

        return Instance.StartCoroutine_Auto(routine);
    }
}

if UNITY_EDITORのところは後で説明するのでスルーしてもらうとして、基本的にはInstance.StartCoroutine_Autoです。ようはMainThreadDispatcherとは、シングルトンのMonoBehaviourであり、FromCoroutineはそいつからコルーチンを起動しているだけなのであった。なんだー、単純。汚れ仕事（コルーチンの起動、MonoBehaviourであること）をMainThreadDispatcherにだけ押し付けることにより、それ以外の部分が平和に浄化される！

コルーチンの起動が一極集中して、それで実行効率とか大丈夫なの？というと存外大丈夫っぽいので大丈夫。実際、私の会社ではこないだ一本iOS向けにゲームをリリースしましたがちゃんと動いてます。しかしそうなるとStartCoroutineはMonoBehaviourのインスタンスメソッドではなく、静的メソッドであって欲しかった……。

その他、SendStartCoroutineはスレッドセーフ（他スレッドから呼ばれた場合はキューに突っ込んでメインスレッドに戻ってから起動する）なのと、UnityEditorからの起動を可能にしています（EditorThreadDispatcher.Instance.PseudoStartCoroutine経由で起動する）。なので、普通にStartCoroutineを呼ぶ以上のメリットを提供できているかな、と。

UnityEditorでコルーチンを実行する

Editorでコルーチンを動かせないのは存外不便です。WWWも動かせないし……。UniRxではFromCoroutine経由で実行すると、内部でMainThreadDispatcher.SendStartCoroutine経由になることにより、Editorで実行できます。使い方は本当にFromCoroutineしてSubscribeするだけ、と、通常時のフローとまるっきり一緒です。ここで毎回エディターの時は、通常の時は、と書き分けるのはカッタルイですからね。汚れ仕事はMainThreadDispatcherが一手に引き受けています。そんな汚れ仕事はこんな感じの実装です。

class EditorThreadDispatcher
{
    // 中略
    
    ThreadSafeQueueWorker editorQueueWorker= new ThreadSafeQueueWorker();

    EditorThreadDispatcher()
    {
        UnityEditor.EditorApplication.update += Update;
    }
    
    // 中略
    
    void Update()
    {
        editorQueueWorker.ExecuteAll(x => Debug.LogException(x));
    }

    // 中略

    public void PseudoStartCoroutine(IEnumerator routine)
    {
        editorQueueWorker.Enqueue(() => ConsumeEnumerator(routine));
    }

    void ConsumeEnumerator(IEnumerator routine)
    {
        if (routine.MoveNext())
        {
            var current = routine.Current;
            if (current == null)
            {
                goto ENQUEUE;
            }

            var type = current.GetType();
            if (type == typeof(WWW))
            {
                var www = (WWW)current;
                editorQueueWorker.Enqueue(() => ConsumeEnumerator(UnwrapWaitWWW(www, routine)));
                return;
            }
            else if (type == typeof(WaitForSeconds))
            {
                var waitForSeconds = (WaitForSeconds)current;
                var accessor = typeof(WaitForSeconds).GetField("m_Seconds", BindingFlags.Instance | BindingFlags.GetField | BindingFlags.NonPublic);
                var second = (float)accessor.GetValue(waitForSeconds);
                editorQueueWorker.Enqueue(() => ConsumeEnumerator(UnwrapWaitForSeconds(second, routine)));
                return;
            }
            else if (type == typeof(Coroutine))
            {
                Debug.Log("Can't wait coroutine on UnityEditor");
                goto ENQUEUE;
            }

        ENQUEUE:
            editorQueueWorker.Enqueue(() => ConsumeEnumerator(routine)); // next update
        }
    }

    IEnumerator UnwrapWaitWWW(WWW www, IEnumerator continuation)
    {
        while (!www.isDone)
        {
            yield return null;
        }
        ConsumeEnumerator(continuation);
    }

    IEnumerator UnwrapWaitForSeconds(float second, IEnumerator continuation)
    {
        var startTime = DateTimeOffset.UtcNow;
        while (true)
        {
            yield return null;

            var elapsed = (DateTimeOffset.UtcNow - startTime).TotalSeconds;
            if (elapsed >= second)
            {
                break;
            }
        };
        ConsumeEnumerator(continuation);
    }
}

ようは、UnityEditor.EditorApplication.updateでジョブキューを回しています。コルーチン(Enumerator)を手動で分解して、EditorApplication.updateに都合の良い形に再編しています。yield return nullがあったらキューに突っ込んで次のupdateに回すことで、擬似的にStartCorotineを再現。WaitForSecondsだったらリフレクションで内部の秒数を取ってきて（ひどぅい）ぐるぐるループを展開。などなど。

仕組み的には単純、なんですが結構効果的で便利かな、と。ユーザーは全くそれを意識する必要がないというのが一番いいトコですね。

ちなみにアセットストアからダウンロードできるバージョンでは、まだこの仕組みは入ってません（すびばせん！）。GitHubの最新コードか、あとは、ええと、近いうちにアップデート申請しますので来年には使えるようになっているはずです。。。

まとめ

コルーチンをコルーチンたらしめているのは消費者であるStartCoroutineであって、IEnumerator自体はただのイテレータにすぎない。なので、分解も可能だし、他の形式に展開することもできる。

UniRx経由でコルーチンを実行すると「色々なものと合成できる」「（複数の）戻り値を扱える」「キャンセルが容易」「MonoBehaviourが不要」「スレッドセーフ」「エディターでも実行可能」になる。いいことづくめっぽい！Reactive Programmingの力！そんな感じに、UniRxはなるべくシームレスにRxの世界とUnityの世界を繋げるような仕組みを用意しています。是非ダウンロードして、色々遊んでみてください。

Profile

Yoshifumi Kawai

Cysharp, Inc
CEO/CTO

Microsoft MVP for Developer Technologies(.NET)
April 2011
|
July 2025

X:@neuecc GitHub:neuecc

Archive