A signal is a stream with a cache.
Whereas a 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 a 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, closeable 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 parameters
- V
-
The type of the value held in the signal.
Value parameters
- value
-
The option of the last value published in the signal or
Noneif the signal was not initialized yet.
Attributes
Members list
Value members
Concrete methods
An alias to and.
An alias to and.
Attributes
An alias for sameAs
An alias for sameAs
Attributes
An alias to xor.
An alias to xor.
Attributes
Assuming that both the value of this signal and the value of the other signal can be interpreted as a boolean, this method creates a new signal of type Boolean by applying logical AND.
Assuming that both the value of this signal and the value of the other signal can be interpreted as a boolean, this method creates a new signal of type Boolean by applying logical AND.
Value parameters
- other
-
The other signal with the value type that can be interpreted as
Boolean
Attributes
- Returns
-
A new signal of
Boolean.
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 parameters
- Z
-
The value type of the new signal.
Value parameters
- pf
-
A partial function which for the original value of the type
Vmay produce a value of the typeZ.
Attributes
- 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 parameters
- Y
-
The value type of the new signal.
- Z
-
The value type of the other signal.
Value parameters
- 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.
Attributes
- 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 parameters
- ec
-
The execution context on which the check will be done
- value
-
The value to test
Attributes
- 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.
Attributes
- 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 parameters
- Z
-
The value type of the fallback signal.
Value parameters
- fallback
-
Another signal of the same or different value type.
Attributes
- 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].
Attributes
- 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 parameters
- ec
-
The execution context on which the check will be done
- f
-
The condition tested on the signal's value
Attributes
- 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 parameters
- predicate
-
A filtering function which for any value of the original signal returns true or false.
Attributes
- 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 parameters
- Z
-
The value type of the new signal.
Value parameters
- f
-
The function mapping each event of type
vto a signal of the typeZ.
Attributes
- 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 parameters
- Z
-
The type of the value of the nested signal.
Attributes
- 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.
Attributes
- Returns
-
The current value of the signal or the value it will be set to in the next update.
An alias to the future method.
An alias to the future method.
Attributes
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 parameters
- Z
-
The value type of the new signal.
Value parameters
- f
-
The function mapping the value of the original signal into the value of the new signal.
Attributes
- Returns
-
A new signal
Assuming that both the value of this signal and the value of the other signal can be interpreted as a boolean, this method creates a new signal of type Boolean by applying logical NAND.
Assuming that both the value of this signal and the value of the other signal can be interpreted as a boolean, this method creates a new signal of type Boolean by applying logical NAND.
Value parameters
- other
-
The other signal with the value type that can be interpreted as
Boolean
Attributes
- Returns
-
A new signal of
Boolean.
Assuming that both the value of this signal and the value of the other signal can be interpreted as a boolean, this method creates a new signal of type Boolean by applying logical NOR.
Assuming that both the value of this signal and the value of the other signal can be interpreted as a boolean, this method creates a new signal of type Boolean by applying logical NOR.
Value parameters
- other
-
The other signal with the value type that can be interpreted as
Boolean
Attributes
- Returns
-
A new signal of
Boolean.
Assuming that the value of the signal can be interpreted as a boolean, this method creates a new signal of type Boolean with the value opposite to that of the original signal.
Assuming that the value of the signal can be interpreted as a boolean, this method creates a new signal of type Boolean with the value opposite to that of the original signal.
Attributes
- Returns
-
A new signal of
Boolean.
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 parameters
- body
-
A function which is called initially, when registered in the signal, and then every time the value of the signal changes.
- ec
-
An
ExecutionContextin which the body function will be executed. - eventContext
-
An EventContext which will register the Subscription for further management (optional)
Attributes
- 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 parameters
- 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)
Attributes
- 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") }
Attributes
- 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 parameters
- Z
-
The type of the value returned by the
selectfunction.
Value parameters
- 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.
Attributes
- Returns
-
A new signal of the same value type as this one, which updates only if the
selectfunction 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") }
Attributes
- Returns
-
A new future which finishes either immediately or as soon as the value of the original signal is true.
Assuming that both the value of this signal and the value of the other signal can be interpreted as a boolean, this method creates a new signal of type Boolean by applying logical OR.
Assuming that both the value of this signal and the value of the other signal can be interpreted as a boolean, this method creates a new signal of type Boolean by applying logical OR.
Value parameters
- other
-
The other signal with the value type that can be interpreted as
Boolean
Attributes
- Returns
-
A new signal of
Boolean.
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 parameters
- fallback
-
Another signal of the same value type.
Attributes
- 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 parameters
- 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.
Attributes
- Returns
-
A new Subscription to this signal.
- See also
Creates a boolean signal where the value is the result of comparison of current values in both the original signals. This method uses Scala equals internally and for the sake of consistency with how equals works in Scala, sameAs allows for comparison between values of different types - there still may exist a valid equals for them.
Creates a boolean signal where the value is the result of comparison of current values in both the original signals. This method uses Scala equals internally and for the sake of consistency with how equals works in Scala, sameAs allows for comparison between values of different types - there still may exist a valid equals for them.
If any of the original signals is empty, the result signal will stay empty as well.
Value parameters
- other
-
The other signal used in comparison
Attributes
- Returns
-
A new boolean 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.
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 parameters
- Z
-
The value type of the new signal.
Value parameters
- 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.
Attributes
- 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 parameters
- delay
-
The time interval used for throttling.
Attributes
- 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.
Attributes
Assuming that both the value of this signal and the value of the other signal can be interpreted as a boolean, this method creates a new signal of type Boolean by applying logical XOR.
Assuming that both the value of this signal and the value of the other signal can be interpreted as a boolean, this method creates a new signal of type Boolean by applying logical XOR.
Value parameters
- other
-
The other signal with the value type that can be interpreted as
Boolean
Attributes
- Returns
-
A new signal of
Boolean.
Zips this signal with the given one.
Zips this signal with the given one.
Type parameters
- Z
-
The type of the values of the other signal.
Value parameters
- other
-
The other signal with values of the same or a different type.
Attributes
- 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.
An alias for pipeTo.
An alias for pipeTo.
Attributes
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.
Attributes
- Returns
-
The current instance, so that
disableAutoworingcan 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.
Attributes
- Inherited from:
- EventSource
Checks if there are any subscribers registered in this EventRelay.
Checks if there are any subscribers registered in this EventRelay.
Attributes
- Returns
-
true if any subscribers are registered, false otherwise
- 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 parameters
- subscriber
-
An instance of a subscriber class, known to the class implementing this
EventRelay
Attributes
- 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 parameters
- subscriber
-
An instance of a subscriber class, known to the class implementing this
EventRelay
Attributes
- 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.
Attributes
- Inherited from:
- EventSource
Attributes
- Inherited from:
- EventSource
Concrete fields
a 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.
a 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.
Attributes
a 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.
a 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.