Return

1. 概要

Return は、最も基本的なファクトリメソッドです。単一の値を発行し、即座に完了します。

TimeProvider と TimeSpan を指定するオーバーロードを使うと、値の発行を非同期的に、または指定時間だけ遅延させることができます。

また、R3 では Unit、bool、int に対してボクシングを回避する最適化オーバーロードが用意されています。

2. シグネチャ

基本

public static Observable<T> Return<T>(T value)

指定した値を即座に発行し、完了します。最もシンプルな形式です。

Observable.Return(42)

遅延付き（TimeProvider）

public static Observable<T> Return<T>(T value, TimeProvider timeProvider, CancellationToken cancellationToken = default)
public static Observable<T> Return<T>(T value, TimeSpan dueTime, TimeProvider timeProvider, CancellationToken cancellationToken = default)

TimeProvider のみを指定した場合、値の発行が非同期的に行われます（タイミングは TimeProvider に委ねられます）。TimeSpan も指定すると、その時間だけ遅延してから値を発行します。

// 非同期的に発行
Observable.Return("hello", TimeProvider.System)

// 1 秒後に発行
Observable.Return("hello", TimeSpan.FromSeconds(1), TimeProvider.System)

型別最適化

public static Observable<Unit> Return(Unit value)
public static Observable<bool> Return(bool value)
public static Observable<int> Return(int value)

Unit、bool、int を直接受け取るオーバーロードです。ジェネリック版と異なり、ボクシングやアロケーションを回避するために内部的に最適化されています。

Observable.Return(Unit.Default)  // Unit 最適化
Observable.Return(true)          // bool 最適化
Observable.Return(100)           // int 最適化

オーバーロードの使い分け

overload	使う場面
Return<T>(T)	任意の型の値を即座に発行する
Return<T>(T, TimeProvider)	非同期的に発行したい場合
Return<T>(T, TimeSpan, TimeProvider)	指定時間だけ遅延して発行したい場合
Return(Unit) / Return(bool) / Return(int)	よく使う型をアロケーションなしで発行する

3. マーブルダイアグラム

Return は購読されると値 x を 1 つ発行し、直後に完了通知を送ります。遅延付きオーバーロードの場合は、指定した時間が経過してから同じ動作を行います。

4. サンプルコード

using R3;

// 基本: 単一の値を即座に発行
Observable.Return(42)
    .Subscribe(x => Console.WriteLine($"値: {x}"));
// 出力: 値: 42

// 遅延付き: 1 秒後に値を発行
Observable.Return("delayed", TimeSpan.FromSeconds(1), TimeProvider.System)
    .Subscribe(
        x => Console.WriteLine($"値: {x}"),
        _ => Console.WriteLine("完了"));
// 出力（1 秒後）: 値: delayed
// 出力: 完了

// Unit 最適化: シグナルとして使用
Observable.Return(Unit.Default)
    .Subscribe(_ => Console.WriteLine("通知を受信"));
// 出力: 通知を受信

5. 補足

ReturnUnit との違い

ReturnUnit は Observable.Return(Unit.Default) と同等ですが、引数なしで呼び出せるため、シグナル用途ではより簡潔に記述できます。

ReturnFrame との違い

時間ベースの遅延ではなく、フレーム単位の遅延が必要な場合（ゲームや UI フレームワーク向け）は ReturnFrame を使用してください。