A signal is an event stream with a cache.
A signal is an event stream with a cache.
Whereas an event stream holds no internal state and just passes on events it receives, a signal keeps the last value it received. A new subscriber function registered in an event stream will be called only when a new event is published. A new subscriber function registered in a signal will be called immediately (or as soon as possible on the given execution context) with the current value of the signal (unless it's not initialized yet) and then again when the value changes. A signal is also able to compare a new value published in it with the old one - the new value will be passed on only if it is different. Thus, a signal can help us with optimizing performance on both ends: as a cache for values which otherwise would require expensive computations to produce them every time we need them, and as a way to ensure that subscriber functions are called only when the value actually changes, but not when the result of the intermediate computation is the same as before.
Note that for clarity we talk about events in the event streams, but about values in signals.
An signal of the type V
dispatches values to all functions of the type (V) => Unit
which were registered in
the signal as its subscribers. It provides a handful of methods which enable the user to create new signals by means of composing
the old ones, filtering them, etc., in a way similar to how the user can operate on standard collections, as well as to interact with
Scala futures, cancellable futures, and event streams. Please note that by default a signal is not able to receive events from the outside -
that functionality belongs to SourceSignal.
- Type Params
- V
The type of the value held in the signal.
- Value Params
- value
The option of the last value published in the signal or
None
if the signal was not initialized yet.
- See also
- Companion
- object
Value members
Concrete methods
Creates a new signal of values of the type Z
by applying a partial function which maps the original value of the type V
to a value of the type Z
. If the partial function doesn't work for the current value, the new signal will become empty
until the next update. Basically, it's filter + map.
Creates a new signal of values of the type Z
by applying a partial function which maps the original value of the type V
to a value of the type Z
. If the partial function doesn't work for the current value, the new signal will become empty
until the next update. Basically, it's filter + map.
- Type Params
- Z
The value type of the new signal.
- Value Params
- pf
A partial function which for the original value of the type
V
may produce a value of the typeZ
.
- Returns
A new signal with values of the type
Z
, holding the value produced from the original signal's value by the partial function, or empty if that's not possible.
Combines the current values of this and another signal of the same or different types V
and Z
to produce a signal with the value
of yet another type Y
. Basically, zip + map.
Combines the current values of this and another signal of the same or different types V
and Z
to produce a signal with the value
of yet another type Y
. Basically, zip + map.
- Type Params
- Y
The value type of the new signal.
- Z
The value type of the other signal.
- Value Params
- f
The function which combines the current values of both parent signals to produce the value of the new signal.
- other
The other signal with values of the same or a different type.
- Returns
A new signal with the value of the type
Y
.
A shortcut that checks if the current value (or the first value after initialization) is the given one.
A shortcut that checks if the current value (or the first value after initialization) is the given one.
- Value Params
- ec
The execution context on which the check will be done
- value
The value to test
- Returns
a future of boolean: true if the signal contains the given value, false otherwise
The current value of the signal. If the signal requires some initial work before accessing its value for the first time, it will be done exactly one time. Subsequently, this method will simply return the current value.
The current value of the signal. If the signal requires some initial work before accessing its value for the first time, it will be done exactly one time. Subsequently, this method will simply return the current value.
Please note that this will return an option of the value type. You may get a None
if the signal is not initialized yet
or if it was temporarily cleared and awaits another update. Usually, it's safer to use head
or future
and work with
a future of the value type instead. And if you need to know if the signal is currently empty, use empty
.
- Returns
The current value of the signal.
A generalization of the orElse
method where the fallback signal can have another value type.
If the value of this signal is V
and the value of the fallback signal is Z
, the new signal will return
an Either[Z, V]
. When the parent signal is set, the value of the new signal will be Right(v)
. When the parent
signal becomes empty, the value of the new signal will temporarily switch to Left(z)
where z
is the current value
of the fallback signal. The moment the parent signal is set to a new value again, the new signal will switch back to
Right(v)
.
Only when both signals are empty, the new signal will become empty too.
A generalization of the orElse
method where the fallback signal can have another value type.
If the value of this signal is V
and the value of the fallback signal is Z
, the new signal will return
an Either[Z, V]
. When the parent signal is set, the value of the new signal will be Right(v)
. When the parent
signal becomes empty, the value of the new signal will temporarily switch to Left(z)
where z
is the current value
of the fallback signal. The moment the parent signal is set to a new value again, the new signal will switch back to
Right(v)
.
Only when both signals are empty, the new signal will become empty too.
- Type Params
- Z
The value type of the fallback signal.
- Value Params
- fallback
Another signal of the same or different value type.
- Returns
A new signal with the value being either the value of the parent or the value of the fallback signal if the parent is empty.
Checks if the signal is currently empty.
A signal is usually empty just after creation, if it was not initialized with a value, and it still waits
for the first value to be sent to it. Or it can be a constant Signal.empty[V]
.
Checks if the signal is currently empty.
A signal is usually empty just after creation, if it was not initialized with a value, and it still waits
for the first value to be sent to it. Or it can be a constant Signal.empty[V]
.
- Returns
true if the signal is empty, false otherwise.
- See also
A shortcut that checks if the current value (or the first value after initialization) fulfills the given condition.
A shortcut that checks if the current value (or the first value after initialization) fulfills the given condition.
- Value Params
- ec
The execution context on which the check will be done
- f
The condition tested on the signal's value
- Returns
a future of boolean: true if the signal's value fulfills the given condition, false otherwise
Creates a new Signal[V]
which updates its value only if the new value of the original signal satisfies the filter,
and changes to empty otherwise. Also, if the initial value of the original signal does not satisfy the filter,
the new signal will start empty.
Creates a new Signal[V]
which updates its value only if the new value of the original signal satisfies the filter,
and changes to empty otherwise. Also, if the initial value of the original signal does not satisfy the filter,
the new signal will start empty.
- Value Params
- f
A filtering function which for any value of the original signal returns true or false.
- Returns
A new signal of the same value type.
Creates a new Signal[Z]
by mapping each event of the original Signal[V]
to a new signal and switching to it.
The usual use case is to create a new complex signal not as one big entity with the value being the result of
computations based on a lot of data at once, but to break it into simpler signals connected by flatMaps. At each
step the used signal produces an intermediate value and recomputing that value is not necessary again until
the values used to compute that one are changed too.
Creates a new Signal[Z]
by mapping each event of the original Signal[V]
to a new signal and switching to it.
The usual use case is to create a new complex signal not as one big entity with the value being the result of
computations based on a lot of data at once, but to break it into simpler signals connected by flatMaps. At each
step the used signal produces an intermediate value and recomputing that value is not necessary again until
the values used to compute that one are changed too.
- Type Params
- Z
The value type of the new signal.
- Value Params
- f
The function mapping each event of type
v
to a signal of the typeZ
.
- Returns
A new or already existing signal to which we switch as the result of a change in the value of the original signal.
Flattens a signal whose value type is also a signal.
Flattens a signal whose value type is also a signal.
- Type Params
- Z
The type of the value of the nested signal.
- Returns
A new signal of the value type the same as the value type of the nested signal.
A future with the current value of the signal. The future will finish immediately with the current value of the signal if the value is already set. If the signal is empty, the future will finish when the next update sets the value.
A future with the current value of the signal. The future will finish immediately with the current value of the signal if the value is already set. If the signal is empty, the future will finish when the next update sets the value.
- Returns
The current value of the signal or the value it will be set to in the next update.
Creates a new Signal[Z]
by mapping the value of the type V
of this signal.
Creates a new Signal[Z]
by mapping the value of the type V
of this signal.
- Type Params
- Z
The value type of the new signal.
- Value Params
- f
The function mapping the value of the original signal into the value of the new signal.
- Returns
A new signal
Registers a subscriber in a specified execution context and returns the subscription. An optional event context can also be provided by the user for managing the subscription instead of doing it manually. When the value of the signal changes, the subscriber function will be called in the given execution context instead of the one of the publisher.
Registers a subscriber in a specified execution context and returns the subscription. An optional event context can also be provided by the user for managing the subscription instead of doing it manually. When the value of the signal changes, the subscriber function will be called in the given execution context instead of the one of the publisher.
- Value Params
- body
A function which is called initially, when registered in the signal, and then every time the value of the signal changes.
- ec
An
ExecutionContext
in which the body function will be executed.- eventContext
An EventContext which will register the Subscription for further management (optional)
- Returns
A Subscription representing the created connection between the signal and the body function
- See also
- Definition Classes
Registers a subscriber which will always be called in the same execution context in which the value of the signal was changed. An optional event context can be provided by the user for managing the subscription instead of doing it manually.
Registers a subscriber which will always be called in the same execution context in which the value of the signal was changed. An optional event context can be provided by the user for managing the subscription instead of doing it manually.
- Value Params
- body
A function which is called initially, when registered in the signal, and then every time the value of the signal changes.
- eventContext
An EventContext which will register the Subscription for further management (optional)
- Returns
A Subscription representing the created connection between the signal and the body function
- See also
- Definition Classes
Assuming that the value of the signal can be interpreted as a boolean, this method returns a future
of type Unit
which will finish with success when the value of the original signal is false.
Assuming that the value of the signal can be interpreted as a boolean, this method returns a future
of type Unit
which will finish with success when the value of the original signal is false.
val signal = Signal[Int](2)
signal.map(_ % 2 == 0).onFalse.foreach { _ => println("This is the first time the value of the signal is odd") }
- Returns
A new future which finishes either immediately or as soon as the value of the original signal is false.
Creates a new signal of the same value type which changes its value to the changed value of the parent signal only if
the given select
function returns different results for the old and the new value. If the results of the select
functions are equal, then even if the new value of the original signal is actually different from the old one, the value
of the new signal stays the same.
Creates a new signal of the same value type which changes its value to the changed value of the parent signal only if
the given select
function returns different results for the old and the new value. If the results of the select
functions are equal, then even if the new value of the original signal is actually different from the old one, the value
of the new signal stays the same.
Consider the following example:
val parent = Signal[Int](3)
val oddEvenSwitch = parent.onPartialUpdate { _ % 2 == 0 }
oddEvenSwitch.foreach { _ => println(s"The value switched between odd and even") }
Here, the value of oddEvenSwitch
will update only if the new value is even if the old one was odd and vice versa.
So, if we publish new odd values to parent
(1, 5, 9, 7, ...) the value of oddEvenSwitch
will stay at 3. Only
when we publish an even number to parent
(say, 2), the value oddEventSwitch
will change. And from now on it will
stay like that until we publish an odd number to the parent.
- Type Params
- Z
The type of the value returned by the
select
function.
- Value Params
- select
A function mapping from the current value of the original signal to another value which will be used for checking if the new signal should update.
- Returns
A new signal of the same value type as this one, which updates only if the
select
function gives different results for the old and the new value of the parent signal.
Assuming that the value of the signal can be interpreted as a boolean, this method returns a future
of type Unit
which will finish with success when the value of the original signal is true.
Assuming that the value of the signal can be interpreted as a boolean, this method returns a future
of type Unit
which will finish with success when the value of the original signal is true.
val signal = Signal[Int](3)
signal.map(_ % 2 == 0).onTrue.foreach { _ => println("This is the first time the value of the signal is even") }
- Returns
A new future which finishes either immediately or as soon as the value of the original signal is true.
Creates a version of this signal which, if the parent signal becomes empty, temporarily uses the value of the given
fallback
signal. The moment the parent signal is set to a new value again, the new signal switches back to it.
Only when both signals are empty, the new signal will become empty too.
Creates a version of this signal which, if the parent signal becomes empty, temporarily uses the value of the given
fallback
signal. The moment the parent signal is set to a new value again, the new signal switches back to it.
Only when both signals are empty, the new signal will become empty too.
- Value Params
- fallback
Another signal of the same value type.
- Returns
A new signal of the same value type.
A shorthand for registering a subscriber function in this signal which only purpose is to publish changes to the value of this signal in another SourceSignal. The subscriber function will be called in the execution context of the original publisher.
A shorthand for registering a subscriber function in this signal which only purpose is to publish changes to the value of this signal in another SourceSignal. The subscriber function will be called in the execution context of the original publisher.
- Value Params
- ec
An EventContext which can be used to manage the subscription (optional).
- sourceSignal
he signal in which changes to the value of this signal will be published.
- Returns
A new Subscription to this signal.
- See also
Creates a new signal with the value type Z
where the change in the value is the result of applying a function
which combines the previous value of type Z
with the changed value of the type V
of the parent signal.
Creates a new signal with the value type Z
where the change in the value is the result of applying a function
which combines the previous value of type Z
with the changed value of the type V
of the parent signal.
- Type Params
- Z
The value type of the new signal.
- Value Params
- f
The function which combines the current value of the new signal with the new, changed value of the parent (this) signal to produce a new value for the new signal (might be the same as the old one and then subscribers won't be notified).
- zero
The initial value of the new signal.
- Returns
A new signal with the value of the type
Z
.- Todo
Test if it really works like that, the code is a bit complicated.
Creates a throttled version of this signal which updates no more often than once during the given time interval. If changes to the value of the parent signal happen more often, some of them will be ignored.
Creates a throttled version of this signal which updates no more often than once during the given time interval. If changes to the value of the parent signal happen more often, some of them will be ignored.
- Value Params
- delay
The time interval used for throttling.
- Returns
A new throttled signal of the same value type as the parent.
- See also
An alias for filter
used in the for/yield notation.
An alias for filter
used in the for/yield notation.
This can be useful for more readable chains of asynchronous computations where at some point we want to wait until some condition is fulfilled:
val resultSignal = for {
a <- signalA
b <- signalB
true <- checkCondition(a, b)
c <- signalC
} yield c
Here, resultSignal
will be updated to the value of signalC
only if the current values of signalA
and signalB
fulfill
the condition. If the check fails, resultSignal
will become empty until signalA
or signalB
changes its value and the new
pair fulfills the condition.
Zips this signal with the given one.
Zips this signal with the given one.
- Type Params
- Z
The type of the values of the other signal.
- Value Params
- other
The other signal with values of the same or a different type.
- Returns
A new signal with values being tuples of the value of this signal and the other one. The value of the other signal will be updated every time this or the other signal's value is updated.
Inherited methods
Typically, a newly created event streams and signals are lazy in the sense that till there are no subscriptions to them,
they will not execute any intermediate computations (e.g. assembled to it through maps, flatMaps, etc). After all,
those computations would be ignored at the end. Only when a subscription is created, the computations are performed
for the first time.
disableAutowiring
enforces those computations even if there are no subscribers. It can be useful if e.g. the computations
perform side-effects or if it's important from the performance point of view to have the intermediate results ready
when the subscriber is created.
Typically, a newly created event streams and signals are lazy in the sense that till there are no subscriptions to them,
they will not execute any intermediate computations (e.g. assembled to it through maps, flatMaps, etc). After all,
those computations would be ignored at the end. Only when a subscription is created, the computations are performed
for the first time.
disableAutowiring
enforces those computations even if there are no subscribers. It can be useful if e.g. the computations
perform side-effects or if it's important from the performance point of view to have the intermediate results ready
when the subscriber is created.
- Returns
The current instance, so that
disableAutoworing
can be chained with other method calls.- Inherited from
- EventSource
An alias for the on
method with the default ExecutionContext.
An alias for the on
method with the default ExecutionContext.
- Inherited from
- EventSource
Checks if there are any subscribers registered in this EventRelay
.
Checks if there are any subscribers registered in this EventRelay
.
- Returns
true if any subscribers are registered, false otherwise
- Inherited from
- EventSource
The class which implements this EventRelay
can use this method to notify all the subscribers that a new event
arrived.
The class which implements this EventRelay
can use this method to notify all the subscribers that a new event
arrived.
- Value Params
- call
A function that will perform some action on each subscriber
- Inherited from
- EventSource
Adds a new subscriber instance. The implementing class should handle notifying this subscriber
when a new event arrives. If this is the first subscriber, and disableAutowiring
wasn't called previous,
this will trigger a call to onWire
.
Adds a new subscriber instance. The implementing class should handle notifying this subscriber
when a new event arrives. If this is the first subscriber, and disableAutowiring
wasn't called previous,
this will trigger a call to onWire
.
- Value Params
- subscriber
An instance of a subscriber class, known to the class implementing this
EventRelay
- Inherited from
- EventSource
Removes a previously registered subscriber instance.
If this is the last subscriber, and disableAutowiring
wasn't called previously, this will trigger a call to onUnwire
.
Removes a previously registered subscriber instance.
If this is the last subscriber, and disableAutowiring
wasn't called previously, this will trigger a call to onUnwire
.
- Value Params
- subscriber
An instance of a subscriber class, known to the class implementing this
EventRelay
- Inherited from
- EventSource
Empties the set of subscribers and calls unWire
if disableAutowiring
wasn't called before.
Empties the set of subscribers and calls unWire
if disableAutowiring
wasn't called before.
- Inherited from
- EventSource
Concrete fields
An event stream where each event is a new value of the signal. Every time the value of the signal changes - actually changes to another value - the new value will be published in this stream. The events in the stream are guaranteed to differ. It's not possible to get two equal events one after another.
An event stream where each event is a new value of the signal. Every time the value of the signal changes - actually changes to another value - the new value will be published in this stream. The events in the stream are guaranteed to differ. It's not possible to get two equal events one after another.
An event stream where each event is a tuple of the old and the new value of the signal.
Every time the value of the signal changes - actually changes to another value - the new value will be published in this stream,
together with the old value which you can use to check what exactly changed. The old value is wrapped in an Option
: if the signal
was previously empty, the old value will be None
otherwise it will be Some[V]
.
The values are guaranteed to differ, i.e. if you get a tuple (Some(oldValue), newValue)
then oldValue != newValue
.
An event stream where each event is a tuple of the old and the new value of the signal.
Every time the value of the signal changes - actually changes to another value - the new value will be published in this stream,
together with the old value which you can use to check what exactly changed. The old value is wrapped in an Option
: if the signal
was previously empty, the old value will be None
otherwise it will be Some[V]
.
The values are guaranteed to differ, i.e. if you get a tuple (Some(oldValue), newValue)
then oldValue != newValue
.