Functional Reactive Programming

Extension

Functional Reactive Programming (FRP) deals with with Event Processing, data flow and propagation of change.It is a composable/modular way to code event-driven logic. Events come in while the program is running, most often, at unpredictable times and should be processed and routed to multiple destinations. We can describe these dataflow connections as a network, connecting inputs to outputs. The network itself is functional, i.e., it's formed by chaining functions which do not present any visible state to the user and no not cause side-effects (posting, chainging synths, changing outside variables, etc).

The FRP classes follow more or less the API of reactive-banana (Haskell library - http://www.haskell.org/haskellwiki/Reactive-banana) and were originally based on code from reactive-web (Scala library - http://reactive-web.tk/).

The key points to keep in mind regarding FRP are:

• FPSignals and EventStreams represent events that can happen at any time. Signals are continuous (they have a "now" value) while event streams are discrete (no "now" value).
• An event network connects inputs (MIDI, GUI, OSC, timer, etc) to outputs (these are actions like setting an argument to a synth, drawing on screen, etc) via signals and event streams.
• signals and event streams when placed in an event network are automatically connected to inputs and outputs when the network is compiled or started and are automatically disconnected when the network is stopped. There is no need for explicit registration and de-registration of callbacks.

Event streams and Signals

Thw two main abstractions of this FRP library are event streams and signals.

You can think of EventStreams as Collections of elements tagged with a time value. It is encoded with subclasses of EventStream.EventStream[A] ~ [ T(Time, A) ]

Signals difer from EventStreams in that it's value is know at each moment in time. Signals are encoded with the FPSignal class hierarchy. In FPLib signals are always step functions, that is they hold a value constant until the next value arrives.FPSignal[A] ~ Time -> A

The main use for signals is to keep around the emmited value. This is handy for:

• letting an event stream use previous values of some other signal,
• letting an event stream use previous values of itself
• Applying n-ary functions (which need to remember the last value of the other n-1 arguments whenever they get a value.

It's possible to create a signal from an event stream and vice-versa by using the 'changes' and 'hold' methods.sig1 = es1.hold(0.0) es2 = sig2.changes

EventNetwork

The event network graph can be specified using EventNetwork or the jit style ENdef. The recommended way to use FRP in FPLib is with ENdef as seen in the example below. The do and fire methods should be used only for quick testing, not for actual instruments or guis.( //Setup GUI a = Slider(); b = Slider(); w = Window(bounds:Rect(200,200,200,100)).layout_( HLayout( StaticText().string_("In:"), a, StaticText().string_("Out:"), b ) ); w.front; ) //start event graph ( ENdef(\graph1,{ //in var aSig = a.enIn; //try changing the function in the collect method //and re-evaluate the ENdef, the gui behaviour will update. var sig = aSig.collect{ |x| 1.0 - x }; //out b.enSinkValue( sig ); }).start; ) ENdef(\graph1).stop

Combinators

Complex networks for event processing are created using the combinator methods.

You can think of EventStreams as Collections of elements over time. Therefore the methods of collections will work as you expect.

select

eventSource.select(f) only outputs a value if f.(value) is true.

x.select(_<0.04)

Collect

eventSource.collect(f) returns a new EventStream, that for every event that this EventStream fires, that one will fire an event that is the result of applying 'f' to this EventStream's event.x.collect(_*100)

inject

eventSource.inject(initialState,f) This method can be used to keep state or accumulate values. f must receive two variables, the first is the current state and second is the last value received. Only works on event streams as signals must always have a current value.[1,2,3,4,5].inject(0.0,{ |state,v| state + v })

Sum values:( x = EventSource(); y = x.inject(0.0,{ |state,v| state + v }); y.do{ |v| postln("I got a "++v) }; x.fire(1); x.fire(4); x.fire(7); x.fire(12); )

Add values to array:( x = EventSource(); y = x.inject([],{ |state,v| state ++ [v] }); y.do{ |v| postln("I got a "++v) }; x.fire(1); x.fire(4); x.fire(7); x.fire(12); )

Keep last two values:( x = EventSource(); y = x.inject([0.0,0.0],{ |state,v| [state[1],v] }); y.do{ |v| postln("I got a "++v) }; x.fire(1); x.fire(4); x.fire(7); x.fire(12); )

switchTo - Dynamic Event Switching

This method allows selecting which events to output depending on the values output by some other EventStream. This is a form of dynamic graph change, so based on a new event a node might be connected a different node, or even a new node created. Many common situations can be dealt with without using switchTo.

es.switchTo(f) creates a new EventStream that consists of the events of the EventStreams returned by f. f is applied on every event of the original EventStream, and its returned EventStream is used until the next event fired by the original EventStream, at which time the previously returned EventStream is no longer used and a new one is used instead.

Combinining signals with functions.

A common requirement is to combine the output of n signals into 1 signal by running an n-argument function on each incoming value of the signals. This is done using the applicative functor combinators (<*>, <%> ):( x = Var(1.0); y = Var(1.0); z = Var(1.0); //when you add a side-effecting function w it will fire an initial value w = { |x,y,z| x + y + z } <%> x <*> y <*> z; w.do( postln(_) ); ) //and then it will fire when you change any x, y or z x.value_(9.0); y.value_(3.0); z.value_(24.0);

Acessing last value

In a language such as Haskell it is possible to have mutually recursive values. These are values where they both appear in the definition of each other. This would let us define an event stream that depends on it's own past values by defining it it terms of the signal obtained from it with hold. The code for an event stream that sums incoming values with its last value looks like:e2 = (+) <$> b <@> e1 b = stepper 0 e2

Unfortunatelly this cannot be done in SuperCollider since we cannot define mutually recursive variables. To get around this limitation we can directly probe the value of the signal obtained from hold using the 'now' method. The now method is essentially performing an IO operation which usually wouldn't be acceptable inside an event graph, but for this particular case it is very handy and doesn't have drawbacks. The code above then translates in FPLib to:sum = { |a| a + sumSig.now } <%> nb1S; sumSig = sum.hold(0);

Because the call to now is done inside an anonymous function is delayed and therefore doesn't cause an error at the definition line.//sum with last value ( //Setup GUI a = NumberBox(); b = NumberBox(); w = Window(bounds:Rect(200,200,200,100)).layout_( HLayout( StaticText().string_("In:"), a, StaticText().string_("Out:"), b ) ); w.front; ) //start Event Network ( ENdef(\sum,{ var sumSig, sum, sumSig2; var rate = 0.8; //in var nb1S = a.enInES; sum = { |a| a + sumSig.now } <%> nb1S; sumSig = sum.hold(0); //out b.enSinkValue( sumSig ); }).start; ) //now type numbers into the first number box ENdef(\sum).stop; w.close;

Manual connection and diconnection of EventStreams and FPSignals

Usually it is recommended to use EventNetwork for automatic management of connections. In any case it's also possible manage connections explicitelly.

Suppose we have the following network:

We can reset the original EventSource which will remove all the branches that start from it. Those branches will be garbage collected.

If you want to disconnect only some branches you can use remove :

We can also disconnect part of the network conditionally on the incoming values: