Mutable

Creates a new event stream that produces events from this event stream only after that produces an event.

After that emits some event, all events from this are produced on the resulting event stream. If that unreacts before an event is produced on this, the resulting event\ stream unreacts. If this unreacts, the resulting event stream unreacts.

Filters events from this event stream and maps them in the same time.

The collect combinator uses a partial function pf to filter events from this event stream. Events for which the partial function is defined are mapped using the partial function, others are discarded.

Note: This combinator is defined only for event streams that contain reference events. You cannot call it for event streams whose events are primitive values, such as Int. This is because the PartialFunction class is not itself specialized.

Collects values from the event stream by applying a partial function, if possible.

Concatenates the events produced by all the event streams emitted by this.

This operation is only available for event stream values that emit other event streams as events. Once this and all the event streams unreact, this event stream unreacts.

Use case:

def concat[S](): Events[S]

Note: This operation potentially buffers events from the nested event streams. Unless each event stream emitted by this is known to unreact eventually, this operation should not be called.

Creates a concatenation of this and that event stream.

The resulting event stream produces all the events from this event stream until this unreacts, and then outputs all the events from that that happened before and after this unreacted. To do this, this operation potentially caches all the events from that. When that unreacts, the resulting event stream unreacts.

Use case:

def concat(that: Events[T]): Events[T]

Note: This operation potentially caches events from that. Unless certain that this eventually unreacts, concat should not be used.

Emits the total number of events produced by this event stream.

The returned value is a scala.reactive.Signal that holds the total number of emitted events.

time  ---------------->
this  ---x---y--z--|
count ---1---2--3--|

Drops n events from this event stream, and emits the rest.

Drop all events after an event that satisfies a predicate.

This is similar to takeWhile, but includes the event that satisfies the predicate.

time                ------------------------>
this                -0---1--2--3-4--1-5--2-->
dropAfter(_ == 4)       -1--2--3-4|

Returns a new event stream that forwards the events from this event stream as long as they satisfy the predicate p.

After an event that does not specify the predicate occurs, the resulting event stream unreacts.

If the predicate throws an exception, the exceptions is propagated, and the resulting event stream unreacts.

time             ------------------------>
this             -0---1--2--3-4--1-5--2-->
dropWhile(_ < 4)     ---------4--1-5--2-->

Filters events from this event stream value using a specified predicate p.

Only events from this for which p returns true are emitted on the resulting event stream.

Returns an event stream that forwards from the first active nested event stream.

Regardless of the order in which the nested event streams were emitted, only the nested event stream that is the first to emit an event gets chosen.

This is illustrated in the following, where the second event stream in this is the first to emit an event.

time   --------------------------->
this       ------4--7---11-------->
             --1------2-----3----->
                 --------0---5---->
first  --------1------1-----3----->

Returns the first event emitted by this event stream.

This method will return immediately and will not block.

This method will return a value only if this event stream emits one or more values on subscription. Otherwise, this method throws a NoSuchElementException.

Returns an event stream that ignores all exceptions in this event stream.

Returns a new event stream that maps events from this event stream using the mapping function f.

time    --------------------->
this    --e1------e2------|
mapped  --f(e1)---f(e2)---|

Mutates multiple mutable event stream values m1, m2 and m3 each time that this event stream produces an event.

Note that the objects m1, m2 and m3 are mutated simultaneously, and events are propagated after the mutation ends. This version of the mutate works on multiple event streams.

Mutates multiple mutable event stream values m1 and m2 each time that this event stream produces an event.

Note that the objects m1 and m2 are mutated simultaneously, and events are propagated after the mutation ends. This version of the mutate works on multiple event streams.

Mutates the target mutable event stream called mutable each time this event stream produces an event.

Here is an example, given an event stream of type r:

val eventLog = new Events.Mutable(mutable.Buffer[String]())
val eventLogMutations = r.mutate(eventLog) { buffer => event =>
  buffer += "at " + System.nanoTime + ": " + event
} // <-- eventLog event propagated

Whenever an event arrives on r, an entry is added to the buffer underlying eventLog. After the mutation completes, a modification event is produced by the eventLog and can be used subsequently:

val uiUpdates = eventLog onEvent { b =>
eventListWidget.add(b.last)
}

Note: No two events will ever be concurrently processed by different threads on the same event stream mutable, but an event that is propagated from within the mutation can trigger an event on this. The result is that mutation is invoked concurrently on the same thread. The following code is problematic has a feedback loop in the dataflow graph:

val emitter = new Events.Emitter[Int]
val mutable = new Events.Mutable[mutable.Buffer[Int]()]
emitter.mutate(mutable) { buffer => n =>
  buffer += n
  if (n == 0)
    emitter.react(n + 1) // <-- event propagated
  assert(buffer.last == n)
}
emitter.react(0)

The statement emitter.react(n + 1) in the mutate block suspends the current mutation, calls the mutation recursively and changes the value of cell, and the assertion fails when the first mutation resumes.

Care must be taken to avoid f from emitting events in feedback loops.

Returns events from the last event stream that this emitted as an event of its own, in effect multiplexing the nested reactives.

The resulting event stream only emits events from the event stream last emitted by this, the preceding event streams are ignored.

This combinator is only available if this event stream emits events that are themselves event streams.

Example:

val currentEvents = new Events.Emitter[Events[Int]]
val e1 = new Events.Emitter[Int]
val e2 = new Events.Emitter[Int]
val currentEvent = currentEvents.mux()
val prints = currentEvent.onEvent(println)

currentEvents.react(e1)
e2.react(1) // nothing is printed
e1.react(2) // 2 is printed
currentEvents.react(e2)
e2.react(6) // 6 is printed
e1.react(7) // nothing is printed

Shown on the diagram:

time            ------------------->
currentEvents   --e1------e2------->
e1              --------2----6----->
e2              -----1----------7-->
currentEvent    --------2----6----->

Use case:

def mux[S](): Events[S]

Registers a callback for react events, disregarding their values

A shorthand for onReaction -- called whenever an event occurs.

This method is handy when the precise event value is not important, or the type of the event is Unit.

Executes the specified block when this event stream unreacts.

Registers callback for react events.

A shorthand for onReaction -- the specified function is invoked whenever there is an event.

Registers callbacks for react and unreact events.

A shorthand for onReaction -- the specified functions are invoked whenever there is an event or an unreaction.

Executes the specified block when this event stream forwards an exception.

Registers callback for events that match the specified patterns.

A shorthand for onReaction -- the specified partial function is applied to only those events for which it is defined.

This method only works for AnyRef values.

Example:

r onMatch {
case s: String => println(s)
case n: Int    => println("number " + s)
}

Use case:

def onMatch(reactor: PartialFunction[T, Unit]): Subscription

Registers a new observer to this event stream.

The observer argument may be invoked multiple times -- whenever an event is produced, or an exception occurs, and at most once when the event stream is terminated. After the event stream terminates, no events or exceptions are propagated on this event stream any more.

Creates an event stream that forwards an event from this event stream only once.

The resulting event stream emits only a single event produced by this event stream after once is called, and then unreacts.

time ----------------->
this --1-----2----3--->
once      ---2|

Forwards an event from this event stream with some probability.

The probability is specified as a real value from 0.0 to 1.0.

Transforms emitted exceptions into an event stream.

If the specified partial function is defined for the exception, an event is emitted. Otherwise, the same exception is forwarded.

Reduces all the events in this event stream.

Emits a single event *after* the event stream unreacts, and then it unreacts itself. For example, the event stream this.reducePast(0)(_ + _) graphically:

time       ----------------->
this       --1-----2----3-|
reducePast ---------------6|

Creates a new event stream s that produces events by consecutively applying the specified operator op to the previous event that s produced and the current event that this event stream value produced.

The scanPast operation allows the current event from this event stream to be mapped into a different event by looking "into the past", i.e. at the event previously emitted by the resulting event stream.

Example -- assume that an event stream r produces events 1, 2 and 3. The following s:

val s = r.scanPast(0)((sum, n) => sum + n)

will produce events 1, 3 (1 + 2) and 6 (3 + 3). Note: the initial value 0 is not emitted. Shown graphically:

time     ----------------->
this     --1-----2----3--->
scanPast --1-----3----6--->|

The scanPast can also be used to produce an event stream of a different type. The following produces a complete history of all the events seen so far:

val s2 = r.scanPast(List[Int]()) {
(history, n) => n :: history
}

The s2 will produce events 1 :: Nil, 2 :: 1 :: Nil and 3 :: 2 :: 1 :: Nil. Note: the initial value Nil is not emitted.

This operation is closely related to a scanLeft on a collection -- if an event stream were a sequence of elements, then scanLeft would produce a new sequence whose elements correspond to the events of the resulting event stream.

Syncs the arrival of events from this and that event stream.

Ensures that pairs of events from this event stream and that event stream are emitted together. If the events produced in time by this and that, the sync will be as follows:

time   --------------------------->
this   ----1---------2-------4---->
that   --1-----2--3--------------->
sync   ----1,1-------2,2-----4,3-->

Pairs of events produced from this and that are then transformed using specified function f. For example, clients that want to output tuples do:

val synced = (a sync b) { (a, b) => (a, b) }

Clients that, for example, want to create differences in pairs of events do:

val diffs = (a sync b)(_ - _)

The resulting event stream unreacts either when this unreacts and there are no more buffered events from this, or when that unreacts and there are no more buffered events from that.

Use case:

def sync[S, R](that: Events[S])(f: (T, S) => R): Events[R]

Note: This operation potentially caches events from this and that. Unless certain that both this produces a bounded number of events before the that produces an event, and vice versa, this operation should not be called.

Emits all the events from this even stream except the first one.

Returns a new event stream that forwards the events from this event stream as long as they satisfy the predicate p.

After an event that does not specify the predicate occurs, the resulting event stream unreacts.

If the predicate throws an exception, the exceptions is propagated, and the resulting event stream unreacts.

time             ------------------------>
this             -0---1--2--3-4--1-5--2-->
takeWhile(_ < 4)     -1--2--3-|

Given an initial event init, converts the event stream into a cold Signal.

Cold signals emit events only when some observer is subscribed to them. As soon as there are no subscribers for the signal, the signal unsubscribes itself from its source event stream. While unsubscribed, the signal **does not update its value**, even if its event source (this event stream) emits events.

If there is at least one subscription to the cold signal, the signal subscribes itself to its event source (this event stream) again.

The unsubscribe method on the resulting signal does nothing -- the subscription of the cold signal unsubscribes only after all of the subscribers unsubscribe, or the source event stream unreacts.

Converts this event stream into a Signal.

The resulting signal initially does not contain an event, and subsequently contains any event that this event stream produces.

Creates an IVar event stream value, completed with the first event from this event stream.

After the IVar is assigned, all subsequent events are ignored. If the self event stream is unreacted before any event arrives, the IVar is closed.

Given an initial event init, converts this event stream into a Signal.

The resulting signal initially contains the event init, and subsequently any event that this event stream produces.

Unifies the events produced by all the event streams emitted by this.

This operation is only available for event stream values that emit other event streams as events. The resulting event stream unifies events of all the event streams emitted by this. Once this and all the event streams emitted by this unreact, the resulting event stream terminates.

Note: if the same event stream is emitted multiple times, it will be subscribed to multiple times.

Example:

time  -------------------------->
this     --1----2--------3------>
             ---------5----6---->
               ---4----------7-->
union -----1----2-4---5--3-6-7-->

Use case:

def union[S](): Events[S]

Creates a union of this and that event stream.

The resulting event stream emits events from both this and that event stream. It unreacts when both this and that event stream unreact.

Returns a new event stream that emits an event when this event stream unreacts.

After the current event stream unreacts, the result event stream first emits an event of type Unit, and then unreacts itself.

Exceptions from this event stream are propagated until the resulting event stream unreacts -- after that, this event stream is not allowed to produce exceptions.

Shown on the diagram:

time            ------------------->
this            --1--2-----3-|
currentEvent    -------------()-|

Creates a new event stream value that produces events from this event stream value until that produces an event.

If this unreacts before that produces a value, the resulting event stream unreacts. Otherwise, the resulting event stream unreacts whenever that produces a value.

Zips values from this event stream with the hint value.