Struct carboxyl::Signal
[−]
[src]
pub struct Signal<A> {
// some fields omitted
}A continuous signal that changes over time.
Signals can be thought of as values that change over time. They have both a continuous and a discrete component. This means that their current value is defined by a function that can be called at any time. That function is only evaluated on-demand, when the signal's current value is sampled. (This is also called pull semantics in the literature on FRP.)
In addition, the current function used to sample a signal may change discretely in reaction to some event. For instance, it is possible to create a signal from an event stream, by holding the last event occurence as the current value of the stream.
Algebraic laws
Signals come with some primitive methods to compose them with each other and with streams. Some of these primitives give the signals an algebraic structure.
Functor
Signals form a functor under unary lifting. Thus, the following laws hold:
- Preservation of identity:
lift!(|x| x, &a) == a, - Function composition:
lift!(|x| g(f(x)), &a) == lift!(g, &lift!(f, &a)).
Applicative functor
By extension, using the notion of a signal of a function, signals also
become an applicative using Signal::new as pure and
|sf, sa| lift!(|f, a| f(a), &sf, &sa) as <*>.
TODO: Expand on this and replace the Haskell reference.
Methods
impl<A: Clone + 'static> Signal<A>
fn new(a: A) -> Signal<A>
Create a constant signal.
fn sample(&self) -> A
Sample the current value of the signal.
impl<A: Clone + Send + Sync + 'static> Signal<A>
fn cyclic<F>(def: F) -> Signal<A> where F: FnOnce(&Signal<A>) -> Signal<A>
Create a signal with a cyclic definition.
The closure gets an undefined forward-declaration of a signal. It is supposed to return a self-referential definition of the same signal.
Sampling the forward-declared signal, before it is properly defined, will cause a run-time panic.
This pattern is useful to implement accumulators, counters and other loops that depend on the sampling behaviour of a signal before a transaction.
fn snapshot<B, C, F>(&self, stream: &Stream<B>, f: F) -> Stream<C> where B: Clone + Send + Sync + 'static, C: Clone + Send + Sync + 'static, F: Fn(A, B) -> C + Send + Sync + 'static
Combine the signal with a stream in a snapshot.
snapshot creates a new stream given a signal and a stream. Whenever
the input stream fires an event, the output stream fires an event
created from the signal's current value and that event using the
supplied function.
let sink1: Sink<i32> = Sink::new(); let sink2: Sink<f64> = Sink::new(); let mut events = sink1.stream().hold(1) .snapshot(&sink2.stream(), |a, b| (a, b)) .events(); // Updating its signal does not cause the snapshot to fire sink1.send(4); // However sending an event down the stream does sink2.send(3.0); assert_eq!(events.next(), Some((4, 3.0)));
impl<A: Clone + Send + Sync + 'static> Signal<Signal<A>>
fn switch(&self) -> Signal<A>
Switch between signals.
This transforms a Signal<Signal<A>> into a Signal<A>. The nested
signal can be thought of as a representation of a switch between different
input signals, that allows one to change the structure of the dependency
graph at run-time. switch provides a way to access the inner value of
the currently active signal.
The following example demonstrates how to use this to switch between two
input signals based on a Button event stream:
// Button type #[derive(Clone, Show)] enum Button { A, B }; // The input sinks let sink_a = Sink::<i32>::new(); let sink_b = Sink::<i32>::new(); // The button sink let sink_button = Sink::<Button>::new(); // Create the output let output = { // Hold input sinks in a signal with some initials let channel_a = sink_a.stream().hold(1); let channel_b = sink_b.stream().hold(2); // A trivial default channel used before any button event let default_channel = Sink::new().stream().hold(0); // Map button to the channel signals, hold with the default channel as // initial value and switch between the signals sink_button .stream() .map(move |b| match b { Button::A => channel_a.clone(), Button::B => channel_b.clone(), }) .hold(default_channel) .switch() }; // In the beginning, output will come from the default channel assert_eq!(output.sample(), 0); // Let's switch to channel A sink_button.send(Button::A); assert_eq!(output.sample(), 1); // And to channel B sink_button.send(Button::B); assert_eq!(output.sample(), 2); // The channels can change, too, of course for k in 4..13 { sink_b.send(k); assert_eq!(output.sample(), k); } sink_button.send(Button::A); for k in 21..77 { sink_a.send(k); assert_eq!(output.sample(), k); }