replay

Replays a sequence to future subscribers after the source finishes, but without resubscribing to the original source.

function replay(bufferSize : uint = 0, windowMs : uint = 0, 
    scheduler : IScheduler = null) : IConnectableObservable.<T>

Where bufferSize is the number of maximum number of values at the end of the sequence to emit when replaying.

Where windowMs is the amount of time, in milliseconds, at the end of the sequence in which values will be used for replaying.

Remarks

Observers that subscribe while the source stream is still sending messages will receive the live messages only.

Observers that subscribe after the source stream has completed (or raised an error) will be replayed the values from the original stream (including onCompleted and onError) without actually resubscribing to the original stream.

If specified, bufferSize indicates the maximum number of “messages” at the end of the stream that will be replayed to subscribers, including onComplete and onError. Messages outside this buffer size will be sent to “live” subscribers, but not to replayed subscribers. If a bufferSize of 0 is specified, no limit is placed on the number of replayed messages.

If specified, windowMs indicates the window of time, in milliseconds, at the end of the sequence in which messages will be kept. Any messages outside this window will be sent to live subscribers, but not to replayed subscribers. If a windowMs of 0 is specified, values will not be constrained within a window of time.

If both a bufferSize and windowMs value is specified, both constraints will apply. That is, only the last bufferSize values within the last windowMs period of time will be replayed.

The returned sequence completes when the source sequence completes.

The returned sequence errors if the source sequence errors.

Marble Diagrams

xs     = source sequence
conn   = replay (recording) sequence
obs 1  = first observer subscribed while source was still active
obs 2,3= subscribed after source completed so receive the events in order


xs     ──o─────o─────o────/
         │     │     │    │
         │     │     │    │
conn   ──o─────o─────o────/
                     │    │
obs 1             ───o────/

obs 3                      ─o─o─o─/

obs 3                        ─o─o─o─/

Scheduling

Unless specified, Scheduler.synchronous will be used to schedule each message to subscribers while replaying.

Return Value

IConnectableObservable.<T>

Examples

var obs : IConnectableObservable = Observable.range(1, 3)
    .replay();

    // Connecting will cause the original source to execute
    // and, as it's synchronous, will complete immediately.
    obs.connect();

    obs.subscribe(
        function(x : int) : void { trace(x); },
        function():void { trace("Completed"); }
    );

    // Trace output is:
    // 1
    // 2
    // 3
    // Completed

var obs : IConnectableObservable = Observable.range(1, 3)
    .replay(3);

    // Connecting will cause the original source to execute
    // and, as it's synchronous, will complete immediately.
    obs.connect();

    obs.subscribe(
        function(x : int) : void { trace(x); },
        function():void { trace("Completed"); }
    );

    // Trace output is:
    // 2 (message 1)
    // 3 (2)
    // Completed (3)

var obs : IConnectableObservable = Observable.interval(500)
    .take(5)
    .replay(1000);

    // Connecting will cause the original source to execute
    // and, as it's synchronous, will complete immediately.
    obs.connect();

    obs.subscribe(
        null,
        function():void
        {
            // The live sequence has completed, we can resubscribe
            // This time it will be synchronous but we'll only get the last 1 second
            // worth of data (2 values in this case)
            obs.subscribe(
                function(x : int) : void { trace(x); },
                function():void { trace("Completed"); }
            );
        });

    // Trace output is:
    // 3
    // 4
    // Completed