EventBuffer
Related Doc:
package reactors
Creates a new event stream that produces events from this event stream only
after that produces an event.
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.
the type of that event stream
the event stream after whose first event the result can start propagating events
the resulting event stream that emits only after that emits
at least once
Returns a new subscription that unsubscribes this, and then executes an action.
Returns a new subscription that unsubscribes this, and then executes an action.
A signal that designates whether the event buffer has events to dequeue.
Groups adjacent events together into batches.
Groups adjacent events together into batches.
Batches have the specified size, unless this unreacts before sufficiently many
events are batched -- in this case, the last batch may have less events than what
was specified.
Note: at the moment, this operation is not specialized, and may incur some boxing when events are primitive elements.
time ---------------------------------------> this -----1---2---3------------4---5--| batch(3) -------------[1, 2, 3]--------[4, 5]-|
the size of each batch, must be greater than 0
event stream with batches of adjacent events
Returns a new subscription that unsubscribes this subscription, and then another.
Returns a new subscription that unsubscribes this subscription, and then another.
Returns a subsequence of events such that subsequent events are not equal.
Returns a subsequence of events such that subsequent events are not equal.
Filters events from this event stream and maps them in the same time.
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.
the type of the mapped event stream
partial function used to filter and map events
evidence that T is a reference type
an event stream with the partially mapped events
Collects values from the event stream by applying a partial function, if possible.
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.
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.
the type of the events in event streams emitted by this
evidence that events of type T produced by this
are actually event stream values of type S
evidence that arrays can be created for type S
the event stream that concatenates all the events from nested event streams
Creates a concatenation of this and that event stream.
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.
another event stream for the concatenation
evidence that arrays can be created for the type T
event stream that concatenates events from this and that
Emits the total number of events produced by this event stream.
Emits the total number of events produced by this event stream.
The returned value is a io.reactors.Signal that holds the total number of emitted events.
time ----------------> this ---x---y--z--| count ---1---2--3--|
an event stream that emits the total number of events emitted
since card was called
Defers events from this stream until first event from the target event stream.
Defers events from this stream until first event from the target event stream.
All events from this event stream are kept in a buffer until the first occurrence
of an event in that event stream. After that, all events from the buffer are
emitted on the resulting event stream, and the rest of the events are forwarded
normally.
This is shown in the following:
time ----------------------> this --1---2-------3---4---> that --------x-------y---z-> delay --------1-2---3---4--->
type of events in that event stream
event stream whose first event flushes the events.
Dequeues a previously enqueued event.
Returns a new event stream that emits an event when this event stream unreacts.
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 -------------()-|
the unreaction event stream and subscription
Drops n events from this event stream, and emits the rest.
Drops n events from this event stream, and emits the rest.
number of events to drop
event stream with the forwarded events
Drop all events after an event that satisfies a predicate.
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|
the predicate that specifies whether to drop subsequent events
event stream with the forwarded events
Returns a new event stream that forwards the events from this event stream as
long as they satisfy the predicate p.
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-->
the predicate that specifies whether to take the element
event stream with the forwarded events
Enqueues an event.
Filters events from this event stream value using a specified predicate p.
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.
the predicate used to filter events
an event streams with the filtered events
Returns an event stream that forwards from the first active nested 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----->
the type of the events in event stream emitted by this
evidence that events of type T produced by this
are actually event streams of type S
event stream that concatenates all the events from nested event streams
Alias for union.
Alias for union.
Returns the first event emitted by this event stream.
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 groups events into event stream using a function.
Returns an event stream that groups events into event stream using a function.
For each unique key returned by the specified function f, the resulting event
stream emits a pair with the key and the event stream of values that map to that
key. The resulting event stream unreacts when this event stream unreacts. The
nested event streams also unreact when this event stream unreacts.
time -----------------------------> this ---3-------5----4------7--8--> groupBy(_ % 2) (1, 3---5-----------7----->) (0, 4-----8-->)
the type of the keys according to which events are grouped
the grouping function for the events
event stream that emits keys and associated event streams
Returns an event stream that ignores all exceptions in this event stream.
Returns an event stream that ignores all exceptions in this event stream.
an event stream that forwards all events, and ignores all exceptions
Incrementally computes state, and emits events to an observer.
Incrementally computes state, and emits events to an observer.
Creates an incrementally updated state, and uses it to emit events to an observer
whenever this event stream emits an event.
type of the output events
function that creates some incrementally computed state, and returns a tuple of the subscription for that state, and the function that emits events from this state
an event stream that emits a sampled view of the state whenever
this event stream emits an event
Returns true iff the buffer is empty.
Converts an event stream of Events[T] to type Events[Try[T]].
Converts an event stream of Events[T] to type Events[Try[T]].
Inbound exceptions are lifted into Failure events, while normal events are
converted into Success events.
Returns a new stream that maps events from this stream using the function f.
Returns a new stream that maps events from this stream using the function f.
time --------------------->
this --e1------e2------|
mapped --f(e1)---f(e2)---|the type of the mapped events
the mapping function
event stream value with the mapped events
Mutates multiple mutable event stream values m1, m2 and m3 each time that
this event stream produces an event.
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.
the type of the first mutable event stream
the type of the second mutable event stream
the type of the third mutable event stream
the first mutable stream
the second mutable stream
the second mutable stream
the function that modifies the mutables
a subscription used to cancel this mutation
Mutates multiple mutable event stream values m1 and m2 each time that this
event stream produces an event.
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.
the type of the first mutable event stream
the type of the second mutable event stream
the first mutable stream
the second mutable stream
the function that modifies the mutables
a subscription used to cancel this mutation
Mutates the target mutable event stream called mutable each time this
event stream produces an event.
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.
the type of the event stream mutable value
the target mutable stream to be mutated with events from this stream
the function that modifies mutable given an event of
type T
a subscription used to cancel this mutation
Returns events from the last event stream that this emitted as an
event of its own, in effect multiplexing the nested reactives.
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]the type of the events in the nested event stream
an implicit evidence that this event stream is nested -- it
emits events of type T that is actually an Events[S]
event stream of events from the event stream last emitted by
this
Returns true iff the buffer is non-empty.
Registers a callback for react events, disregarding their values
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.
the callback invoked when an event arrives
a subscription for unsubscribing from reactions
Executes the specified block when this event stream unreacts.
Executes the specified block when this event stream unreacts.
the callback invoked when this unreacts
a subscription for the unreaction notification
Registers callback for react events.
Registers callback for react events.
A shorthand for onReaction -- the specified function is invoked whenever
there is an event.
the callback for events
a subcriptions for unsubscribing from reactions
Registers callbacks for react and unreact events.
Registers callbacks for react and unreact events.
A shorthand for onReaction -- the specified functions are invoked whenever there
is an event or an unreaction.
called when this event stream produces an event
called when this event stream unreacts
a subscription for unsubscribing from reactions
Executes the specified block when this event stream forwards an exception.
Executes the specified block when this event stream forwards an exception.
the partial function used to handle the exception
a subscription for the exception notifications
Registers callback for events that match the specified patterns.
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
the callback for those events for which it is defined
a subscription for unsubscribing from reactions
Registers a new observer to this event stream.
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.
the observer for react, except and unreact events
a subscription for unsubscribing from reactions
Creates an event stream that forwards an event from this event stream only once.
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|
an event stream with the first event from this
Pipes the events on this input stream to the target channel.
Pipes the events on this input stream to the target channel.
Exceptions are ignored.
Forwards an event from this event stream with some probability.
Forwards an event from this event stream with some probability.
The probability is specified as a real value from 0.0 to 1.0.
the probability to forward an event
the event stream that forwards events with some probability
Transforms emitted exceptions into an event stream.
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.
type of events exceptions are mapped to
partial mapping from functions to events
an event stream that emits events when an exception arrives
Reduces all the events in this event stream.
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|
the type of the events in the resulting event stream
the initial value of the reduce past
the operator that combines the last event and the current one
an event stream that emits the reduction of all events once
Reverses the events of this event stream.
Reverses the events of this event stream.
The events are emitted in the opposite order from what they are emitted on this
event stream. Exceptions are simply piped through in the order in which they
come in.
time -------------------------> this ------1----2-3---| reverse -----------------3-2-1-|
Note: This operation buffers events from this event stream until this
event stream unreacts. No events are emitted before this unreacts. Consequently,
the resulting event stream may buffer events indefinitely, resulting in a memory
leak. Use this operation **only if you can guarantee that the current event
stream is finite**.
Whenever this stream emits, uses the sampling function to emit another event.
Whenever this stream emits, uses the sampling function to emit another event.
This combinator is useful when there is a clear ordering of events in different event stream, and the incremental system state needs to be sampled at specific points in time. The sampling function is guaranteed to be called only once per each emitted event (however, if there are multiple subscribers to the resulting event stream, then the sampling function will be called once for each subscriber).
the type of the sampled events
the sampling function
event stream value with the sampled events
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.
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.
the type of the events in the resulting event stream
the initial value of the scan past
the operator the combines the last produced and the current event into a new one
an event stream that scans events from this event stream
Size of the event buffer.
Creates a sliding window of the events produced in this event stream.
Creates a sliding window of the events produced in this event stream.
time -------------------------------------------> this -----1----2------3----------4---------| batch(3) -----[1]--[2,1]--[3,2,1]----[4,3,2]---|
Note: whenever an event arrives, the sliding window must be updated.
The sliding window is represented with an immutable queue data structure.
This data structure is used to incrementally a new version of the sliding window.
The update operation takes O(1) time, but needs to allocate around 7 objects on
average. That is generally not very expensive, but clients that really need top
performance should use mutate with a mutable queue data structure to maintain
the sliding window.
The resulting Conc.Queue has O(log n) access to elements, where n is the
size of the sliding window. It be converted to an array in O(n) time.
size of the sliding window
the sliding window data structure
The subscription associated with this event buffer.
The subscription associated with this event buffer.
Syncs the arrival of events from this and that 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 buffers 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.
the type of the events in that event stream
the type of the events in the resulting event stream
the event stream to sync with
the mapping function for the pair of events
evidence that arrays can be created for the type T
evidence that arrays can be created for the type S
the event stream with the resulting events
Emits all the events from this even stream except the first one.
Emits all the events from this even stream except the first one.
event stream with the forwarded events
Takes n events from this event stream, and unreacts.
Takes n events from this event stream, and unreacts.
number of events to take
event stream with the forwarded events
Returns a new event stream that forwards the events from this event stream as
long as they satisfy the predicate p.
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-|
the predicate that specifies whether to take the element
event stream with the forwarded events
Given an initial event init, converts the event stream into a cold Signal.
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.
Returns a signal that becomes true when this event stream is done.
Returns a signal that becomes true when this event stream is done.
Same as toEmpty, but emits an event on subscription if signal is non-empty.
Same as toEmpty, but emits an event on subscription if signal is non-empty.
Converts this event stream into a Signal.
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.
the signal version of the current event stream
Streams events from this event stream into an event buffer.
Streams events from this event stream into an event buffer.
Clients must manually call dequeue on the resulting event buffer when they
are ready to release events.
a new event buffer with all the events from this event stream
Creates an IVar event stream value, completed with the first event from
this event stream.
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.
an IVar with the first event from this event stream
Creates an initially empty RCell, updated with events of this event stream.
Creates an initially empty RCell, updated with events of this event stream.
After the first event gets produced, the RCell is assigned this value, and is
from there on not empty. The RCell can also, alternatively, be modified by
clients.
an RCell with the first event from this event stream
Given an initial event init, converts this event stream into a Signal.
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.
an initial value for the signal
the signal version of the current event stream
Unifies the events produced by all the event streams emitted by this.
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]the type of the events in event streams emitted by this
evidence that events of type T produced by this
are actually event stream values of type S
the event stream with the union of all the events from the nested event streams
Creates a union of this and that event stream.
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.
another event stream for the union
the event stream with unified events from this and that
Converts an event stream of Events[Try[S]] to type Events[S].
Converts an event stream of Events[Try[S]] to type Events[S].
Normal events are emitted for Success objects, and exceptions for Failure.
Stops event propagation on the corresponding event stream.
Stops event propagation on the corresponding event stream.
Creates a new event stream value that produces events from this event stream
value until that produces an event.
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.
the type of that event stream
the event stream until whose first event the result propagates events
the resulting event stream that emits only until that emits
Zips values from this event stream with the hint value.
Zips values from this event stream with the hint value.
An event buffer that is simultaneously an event stream.
Events are stored into the buffer with the
enqueuemethod. Events are dequeued and simultaneously emitted with thedequeuemethod. Callingunsubscribeunreacts.Note: this class can only be used inside a single reactor, and is not meant to be shared across multiple threads.
type of the events in this event stream