Up

module React

: sig

Declarative events and signals.

React is a module for functional reactive programming (frp). It provides support to program with time varying values : declarative events and signals. React doesn't define any primitive event or signal, this lets the client choose the concrete timeline.

Consult the semantics, the basics and examples. Open the module to use it, this defines only two types and modules in your scope.

Release 1.2.0 - Daniel Bünzli <daniel.buenzl i@erratique.ch>

Interface

#
type 'a event

The type for events of type 'a.

#
type 'a signal

The type for signals of type 'a.

#
type step

The type for update steps.

#
module E : sig

Event combinators.

Consult their semantics.

#

Primitive and basics

#
type 'a t = 'a event

The type for events with occurrences of type 'a.

#
val never : 'a event

A never occuring event. For all t, [never]t = None.

#
val create : unit -> 'a event * (?step:step -> 'a -> unit)

create () is a primitive event e and a send function. The function send is such that:

  • send v generates an occurrence v of e at the time it is called and triggers an update step.
  • send ~step v generates an occurence v of e on the step step when step is executed.
  • send ~step v raises Invalid_argument if it was previously called with a step and this step has not executed yet or if the given step was already executed.

Warning. send must not be executed inside an update step.

#
val retain : 'a event -> (unit -> unit) -> [
| `R of unit -> unit
]

retain e c keeps a reference to the closure c in e and returns the previously retained value. c will never be invoked.

Raises. Invalid_argument on E.never.

#
val stop : ?strong:bool -> 'a event -> unit

stop e stops e from occuring. It conceptually becomes never and cannot be restarted. Allows to disable effectful events.

The strong argument should only be used on platforms where weak arrays have a strong semantics (i.e. JavaScript). See details.

Note. If executed in an update step the event may still occur in the step.

#
val equal : 'a event -> 'a event -> bool

equal e e' is true iff e and e' are equal. If both events are different from never, physical equality is used.

#
val trace : ?iff:bool signal -> ('a -> unit) -> 'a event -> 'a event

trace iff tr e is e except tr is invoked with e's occurence when iff is true (defaults to S.const true). For all t where [e]t = Some v and [iff]t = true, tr is invoked with v.

#

Transforming and filtering

#
val once : 'a event -> 'a event

once e is e with only its next occurence.

  • [once e]t = Some v if [e]t = Some v and [e]<t = None.
  • [once e]t = None otherwise.
#
val drop_once : 'a event -> 'a event

drop_once e is e without its next occurrence.

  • [drop_once e]t = Some v if [e]t = Some v and [e]<t = Some _.
  • [drop_once e]t = None otherwise.
#
val app : ('a -> 'b) event -> 'a event -> 'b event

app ef e occurs when both ef and e occur simultaneously. The value is ef's occurence applied to e's one.

  • [app ef e]t = Some v' if [ef]t = Some f and [e]t = Some v and f v = v'.
  • [app ef e]t = None otherwise.
#
val map : ('a -> 'b) -> 'a event -> 'b event

map f e applies f to e's occurrences.

  • [map f e]t = Some (f v) if [e]t = Some v.
  • [map f e]t = None otherwise.
#
val stamp : 'b event -> 'a -> 'a event

stamp e v is map (fun _ -> v) e.

#
val filter : ('a -> bool) -> 'a event -> 'a event

filter p e are e's occurrences that satisfy p.

  • [filter p e]t = Some v if [e]t = Some v and p v = true
  • [filter p e]t = None otherwise.
#
val fmap : ('a -> 'b option) -> 'a event -> 'b event

fmap fm e are e's occurrences filtered and mapped by fm.

  • [fmap fm e]t = Some v if fm [e]t = Some v
  • [fmap fm e]t = None otherwise.
#
val diff : ('a -> 'a -> 'b) -> 'a event -> 'b event

diff f e occurs whenever e occurs except on the next occurence. Occurences are f v v' where v is e's current occurrence and v' the previous one.

  • [diff f e]t = Some r if [e]t = Some v, [e]<t = Some v' and f v v' = r.
  • [diff f e]t = None otherwise.
#
val changes : ?eq:('a -> 'a -> bool) -> 'a event -> 'a event

changes eq e is e's occurrences with occurences equal to the previous one dropped. Equality is tested with eq (defaults to structural equality).

  • [changes eq e]t = Some v if [e]t = Some v and either [e]<t = None or [e]<t = Some v' and eq v v' = false.
  • [changes eq e]t = None otherwise.
#
val on : bool signal -> 'a event -> 'a event

on c e is the occurrences of e when c is true.

  • [on c e]t = Some v if [c]t = true and [e]t = Some v.
  • [on c e]t = None otherwise.
#
val when_ : bool signal -> 'a event -> 'a event

Deprecated Use on.
#
val dismiss : 'b event -> 'a event -> 'a event

dismiss c e is the occurences of e except the ones when c occurs.

  • [dimiss c e]t = Some v if [c]t = None and [e]t = Some v.
  • [dimiss c e]t = None otherwise.
#
val until : 'a event -> 'b event -> 'b event

until c e is e's occurences until c occurs.

  • [until c e]t = Some v if [e]t = Some v and [c]<=t = None
  • [until c e]t = None otherwise.
#

Accumulating

#
val accum : ('a -> 'a) event -> 'a -> 'a event

accum ef i accumulates a value, starting with i, using e's functional occurrences.

  • [accum ef i]t = Some (f i) if [ef]t = Some f and [ef]<t = None.
  • [accum ef i]t = Some (f acc) if [ef]t = Some f and [accum ef i]<t = Some acc.
  • [accum ef i] = None otherwise.
#
val fold : ('a -> 'b -> 'a) -> 'a -> 'b event -> 'a event

fold f i e accumulates e's occurrences with f starting with i.

  • [fold f i e]t = Some (f i v) if [e]t = Some v and [e]<t = None.
  • [fold f i e]t = Some (f acc v) if [e]t = Some v and [fold f i e]<t = Some acc.
  • [fold f i e]t = None otherwise.
#

Combining

#
val select : 'a event list -> 'a event
#
val merge : ('a -> 'b -> 'a) -> 'a -> 'b event list -> 'a event

merge f a el merges the simultaneous occurrences of every event in el using f and the accumulator a.

[merge f a el]t = List.fold_left f a (List.filter (fun o -> o <> None) (List.map []tel)).

#
val switch : 'a event -> 'a event event -> 'a event

switch e ee is e's occurrences until there is an occurrence e' on ee, the occurrences of e' are then used until there is a new occurrence on ee, etc..

  • [switch e ee]t = [e]t if [ee]<=t = None.
  • [switch e ee]t = [e']t if [ee]<=t = Some e'.
#
val fix : ('a event -> 'a event * 'b) -> 'b

fix ef allows to refer to the value an event had an infinitesimal amount of time before.

In fix ef, ef is called with an event e that represents the event returned by ef delayed by an infinitesimal amount of time. If e', r = ef e then r is returned by fix and e is such that :

  • [e]t = None if t = 0
  • [e]t = [e']t-dt otherwise

Raises. Invalid_argument if e' is directly a delayed event (i.e. an event given to a fixing function).

Lifting

Lifting combinators. For a given n the semantics is:

  • [ln f e1 ... en]t = Some (f v1 ... vn) if for all i : [ei]t = Some vi.
  • [ln f e1 ... en]t = None otherwise.
#
val l1 : ('a -> 'b) -> 'a event -> 'b event
#
val l2 : ('a -> 'b -> 'c) -> 'a event -> 'b event -> 'c event
#
val l3 : ('a -> 'b -> 'c -> 'd) -> 'a event -> 'b event -> 'c event -> 'd event
#
val l4 : ('a -> 'b -> 'c -> 'd -> 'e) -> 'a event -> 'b event -> 'c event -> 'd event -> 'e event
#
val l5 : ('a -> 'b -> 'c -> 'd -> 'e -> 'f) -> 'a event -> 'b event -> 'c event -> 'd event -> 'e event -> 'f event
#
val l6 : ('a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g) -> 'a event -> 'b event -> 'c event -> 'd event -> 'e event -> 'f event -> 'g event

Pervasives support

#
module Option : sig

Events with option occurences.

#
val some : 'a event -> 'a option event

some e is map (fun v -> Some v) e.

#
val value : ?default:'a signal -> 'a option event -> 'a event

value default e either silences None occurences if default is unspecified or replaces them by the value of default at the occurence time.

  • [value ~default e]t= v if [e]t = Some (Some v).
  • [value ?default:None e]t= None if [e]t = None.
  • [value ?default:(Some s) e]t= v if [e]t = None and [s]t = v.
end
end
#
module S : sig

Signal combinators.

Consult their semantics.

#

Primitive and basics

#
type 'a t = 'a signal

The type for signals of type 'a.

#
val const : 'a -> 'a signal

const v is always v, [const v]t = v.

#
val create : ?eq:('a -> 'a -> bool) -> 'a -> 'a signal * (?step:step -> 'a -> unit)

create i is a primitive signal s set to i and a set function. The function set is such that:

  • set v sets the signal's value to v at the time it is called and triggers an update step.
  • set ~step v sets the signal's value to v at the time it is called and updates it dependencies when step is executed
  • set ~step v raises Invalid_argument if it was previously called with a step and this step has not executed yet or if the given step was already executed.

Warning. set must not be executed inside an update step.

#
val value : 'a signal -> 'a

value s is s's current value.

Warning. If executed in an update step may return a non up-to-date value or raise Failure if the signal is not yet initialized.

#
val retain : 'a signal -> (unit -> unit) -> [
| `R of unit -> unit
]

retain s c keeps a reference to the closure c in s and returns the previously retained value. c will never be invoked.

Raises. Invalid_argument on constant signals.

#
val stop : ?strong:bool -> 'a signal -> unit

stop s, stops updating s. It conceptually becomes const with the signal's last value and cannot be restarted. Allows to disable effectful signals.

The strong argument should only be used on platforms where weak arrays have a strong semantics (i.e. JavaScript). See details.

Note. If executed in an update step the signal may still update in the step.

#
val equal : ?eq:('a -> 'a -> bool) -> 'a signal -> 'a signal -> bool

equal s s' is true iff s and s' are equal. If both signals are constant eq is used between their value (defauts to structural equality). If both signals are not constant, physical equality is used.

#
val trace : ?iff:bool t -> ('a -> unit) -> 'a signal -> 'a signal

trace iff tr s is s except tr is invoked with s's current value and on s changes when iff is true (defaults to S.const true). For all t where [s]t = v and (t = 0 or ([s]t-dt= v' and eq v v' = false)) and [iff]t = true, tr is invoked with v.

From events

#
val hold : ?eq:('a -> 'a -> bool) -> 'a -> 'a event -> 'a signal

hold i e has the value of e's last occurrence or i if there wasn't any.

  • [hold i e]t = i if [e]<=t = None
  • [hold i e]t = v if [e]<=t = Some v
#

Transforming and filtering

#
val app : ?eq:('b -> 'b -> bool) -> ('a -> 'b) signal -> 'a signal -> 'b signal

app sf s holds the value of sf applied to the value of s, [app sf s]t = [sf]t [s]t.

#
val map : ?eq:('b -> 'b -> bool) -> ('a -> 'b) -> 'a signal -> 'b signal

map f s is s transformed by f, [map f s]t = f [s]t.

#
val filter : ?eq:('a -> 'a -> bool) -> ('a -> bool) -> 'a -> 'a signal -> 'a signal

filter f i s is s's values that satisfy p. If a value does not satisfy p it holds the last value that was satisfied or i if there is none.

  • [filter p s]t = [s]t if p [s]t= true.
  • [filter p s]t = [s]t' if p [s]t= false and t' is the greatest t' < t with p [s]t'= true.
  • [filter p e]t = i otherwise.
#
val fmap : ?eq:('b -> 'b -> bool) -> ('a -> 'b option) -> 'b -> 'a signal -> 'b signal

fmap fm i s is s filtered and mapped by fm.

  • [fmap fm i s]t = v if fm [s]t= Some v.
  • [fmap fm i s]t = [fmap fm i s]t' if fm [s]t = None and t' is the greatest t' < t with fm [s]t' <> None.
  • [fmap fm i s]t = i otherwise.
#
val diff : ('a -> 'a -> 'b) -> 'a signal -> 'b event

diff f s is an event with occurrences whenever s changes from v' to v and eq v v' is false (eq is the signal's equality function). The value of the occurrence is f v v'.

  • [diff f s]t = Some d if [s]t = v and [s]t-dt = v' and eq v v' = false and f v v' = d.
  • [diff f s]t = None otherwise.
#
val changes : 'a signal -> 'a event

changes s is diff (fun v _ -> v) s.

#
val sample : ('b -> 'a -> 'c) -> 'b event -> 'a signal -> 'c event

sample f e s samples s at e's occurrences.

  • [sample f e s]t = Some (f ev sv) if [e]t = Some ev and [s]t = sv.
  • [sample e s]t = None otherwise.
#
val on : ?eq:('a -> 'a -> bool) -> bool signal -> 'a -> 'a signal -> 'a signal

on c i s is the signal s whenever c is true. When c is false it holds the last value s had when c was the last time true or i if it never was.

  • [on c i s]t = [s]t if [c]t = true
  • [on c i s]t = [s]t' if [c]t = false where t' is the greatest t' < t with [c]t' = true.
  • [on c i s]t = i otherwise.
#
val when_ : ?eq:('a -> 'a -> bool) -> bool signal -> 'a -> 'a signal -> 'a signal

Deprecated Use on.
#
val dismiss : ?eq:('a -> 'a -> bool) -> 'b event -> 'a -> 'a signal -> 'a signal

dismiss c i s is the signal s except changes when c occurs are ignored. If c occurs initially i is used.

  • [dismiss c i s]t = [s]t' where t' is the greatest t' <= t with [c]t' = None and [s]t'-dt <> [s]t'
  • [dismiss_ c i s]0 = v where v = i if [c]0 = Some _ and v = [s]0 otherwise.
#

Accumulating

#
val accum : ?eq:('a -> 'a -> bool) -> ('a -> 'a) event -> 'a -> 'a signal

accum e i is S.hold i (E.accume i).

#
val fold : ?eq:('a -> 'a -> bool) -> ('a -> 'b -> 'a) -> 'a -> 'b event -> 'a signal

fold f i e is S.hold i (E.foldf i e).

#

Combining

#
val merge : ?eq:('a -> 'a -> bool) -> ('a -> 'b -> 'a) -> 'a -> 'b signal list -> 'a signal

merge f a sl merges the value of every signal in sl using f and the accumulator a.

[merge f a sl]t = List.fold_left f a (List.map []tsl).

#
val switch : ?eq:('a -> 'a -> bool) -> 'a signal signal -> 'a signal

switch ss is the inner signal of ss.

  • [switch ss]t = [[ss]t]t.
#
val bind : ?eq:('b -> 'b -> bool) -> 'a signal -> ('a -> 'b signal) -> 'b signal

bind s sf is switch (map ~eq:( == ) sf s).

#
val fix : ?eq:('a -> 'a -> bool) -> 'a -> ('a signal -> 'a signal * 'b) -> 'b

fix i sf allow to refer to the value a signal had an infinitesimal amount of time before.

In fix sf, sf is called with a signal s that represents the signal returned by sf delayed by an infinitesimal amount time. If s', r = sf s then r is returned by fix and s is such that :

  • [s]t = i for t = 0.
  • [s]t = [s']t-dt otherwise.

eq is the equality used by s.

Raises. Invalid_argument if s' is directly a delayed signal (i.e. a signal given to a fixing function).

Note. Regarding values depending on the result r of s', r = sf s the following two cases need to be distinguished :

  • After sf s is applied, s' does not depend on a value that is in a step and s has no dependents in a step (e.g in the simple case where fix is applied outside a step).
    In that case if the initial value of s' differs from i, s and its dependents need to be updated and a special update step will be triggered for this. Values depending on the result r will be created only after this special update step has finished (e.g. they won't see the i of s if r = s).
  • Otherwise, values depending on r will be created in the same step as s and s' (e.g. they will see the i of s if r = s).
#

Lifting

Lifting combinators. For a given n the semantics is :

[ln f a1 ... an]t = f [a1]t ... [an]t

#
val l1 : ?eq:('b -> 'b -> bool) -> ('a -> 'b) -> 'a signal -> 'b signal
#
val l2 : ?eq:('c -> 'c -> bool) -> ('a -> 'b -> 'c) -> 'a signal -> 'b signal -> 'c signal
#
val l3 : ?eq:('d -> 'd -> bool) -> ('a -> 'b -> 'c -> 'd) -> 'a signal -> 'b signal -> 'c signal -> 'd signal
#
val l4 : ?eq:('e -> 'e -> bool) -> ('a -> 'b -> 'c -> 'd -> 'e) -> 'a signal -> 'b signal -> 'c signal -> 'd signal -> 'e signal
#
val l5 : ?eq:('f -> 'f -> bool) -> ('a -> 'b -> 'c -> 'd -> 'e -> 'f) -> 'a signal -> 'b signal -> 'c signal -> 'd signal -> 'e signal -> 'f signal
#
val l6 : ?eq:('g -> 'g -> bool) -> ('a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g) -> 'a signal -> 'b signal -> 'c signal -> 'd signal -> 'e signal -> 'f signal -> 'g signal

The following modules lift some of Pervasives functions and operators.

#
module Bool : sig
#
val zero : bool signal
#
val one : bool signal
#
val not : bool signal -> bool signal
#
val (&&) : bool signal -> bool signal -> bool signal
#
val (||) : bool signal -> bool signal -> bool signal
#
val edge : bool signal -> bool event

edge s is changes s.

#
val rise : bool signal -> unit event

rise s is E.fmap (fun b -> if b then Some () else None) (edge s).

#
val fall : bool signal -> unit event

fall s is E.fmap (fun b -> if b then None else Some ()) (edge s).

#
val flip : bool -> 'a event -> bool signal

flip b e is a signal whose boolean value flips each time e occurs. b is the initial signal value.

  • [flip b e]0 = not b if [e]0 = Some _
  • [flip b e]t = b if [e]<=t = None
  • [flip b e]t = not [flip b e]t-dt if [e]t = Some _
end
#
module Int : sig
#
val zero : int signal
#
val one : int signal
#
val minus_one : int signal
#
val (~-) : int signal -> int signal
#
val succ : int signal -> int signal
#
val pred : int signal -> int signal
#
val (+) : int signal -> int signal -> int signal
#
val (-) : int signal -> int signal -> int signal
#
val (*) : int signal -> int signal -> int signal
#
val mod : int signal -> int signal -> int signal
#
val abs : int signal -> int signal
#
val max_int : int signal
#
val min_int : int signal
#
val land : int signal -> int signal -> int signal
#
val lor : int signal -> int signal -> int signal
#
val lxor : int signal -> int signal -> int signal
#
val lnot : int signal -> int signal
#
val lsl : int signal -> int signal -> int signal
#
val lsr : int signal -> int signal -> int signal
#
val asr : int signal -> int signal -> int signal
end
#
module Float : sig
#
val zero : float signal
#
val one : float signal
#
val minus_one : float signal
#
val (~-.) : float signal -> float signal
#
val (+.) : float signal -> float signal -> float signal
#
val (-.) : float signal -> float signal -> float signal
#
val (*.) : float signal -> float signal -> float signal
#
val (/.) : float signal -> float signal -> float signal
#
val (**) : float signal -> float signal -> float signal
#
val sqrt : float signal -> float signal
#
val exp : float signal -> float signal
#
val log : float signal -> float signal
#
val log10 : float signal -> float signal
#
val cos : float signal -> float signal
#
val sin : float signal -> float signal
#
val tan : float signal -> float signal
#
val acos : float signal -> float signal
#
val asin : float signal -> float signal
#
val atan : float signal -> float signal
#
val atan2 : float signal -> float signal -> float signal
#
val cosh : float signal -> float signal
#
val sinh : float signal -> float signal
#
val tanh : float signal -> float signal
#
val ceil : float signal -> float signal
#
val floor : float signal -> float signal
#
val abs_float : float signal -> float signal
#
val mod_float : float signal -> float signal -> float signal
#
val frexp : float signal -> (float * int) signal
#
val ldexp : float signal -> int signal -> float signal
#
val modf : float signal -> (float * float) signal
#
val float : int signal -> float signal
#
val float_of_int : int signal -> float signal
#
val truncate : float signal -> int signal
#
val int_of_float : float signal -> int signal
#
val infinity : float signal
#
val neg_infinity : float signal
#
val nan : float signal
#
val max_float : float signal
#
val min_float : float signal
#
val epsilon_float : float signal
#
val classify_float : float signal -> Pervasives.fpclass signal
end
#
module Pair : sig
#
val pair : ?eq:('a * 'b -> 'a * 'b -> bool) -> 'a signal -> 'b signal -> ('a * 'b) signal
#
val fst : ?eq:('a -> 'a -> bool) -> ('a * 'b) signal -> 'a signal
#
val snd : ?eq:('a -> 'a -> bool) -> ('b * 'a) signal -> 'a signal
end
#
module Option : sig
#
val none : 'a option signal

none is S.const None.

#
val some : 'a signal -> 'a option signal

some s is S.map ~eq (fun v -> Some v) None, where eq uses s's equality function to test the Some v's equalities.

#
val value : ?eq:('a -> 'a -> bool) -> default:[
| `Init of 'a signal
| `Always of 'a signal
] -> 'a option signal -> 'a signal

value default s is s with only its Some v values. Whenever s is None, if default is `Always dv then the current value of dv is used instead. If default is `Init dv the current value of dv is only used if there's no value at creation time, otherwise the last Some v value of s is used.

  • [value ~default s]t = v if [s]t = Some v
  • [value ~default:(`Always d) s]t = [d]t if [s]t = None
  • [value ~default:(`Init d) s]0 = [d]0 if [s]0 = None
  • [value ~default:(`Init d) s]t = [value ~default:(`Init d) s]t' if [s]t = None and t' is the greatest t' < t with [s]t' <> None or 0 if there is no such t'.
end
#
module Compare : sig
#
val (=) : 'a signal -> 'a signal -> bool signal
#
val (<>) : 'a signal -> 'a signal -> bool signal
#
val (<) : 'a signal -> 'a signal -> bool signal
#
val (>) : 'a signal -> 'a signal -> bool signal
#
val (<=) : 'a signal -> 'a signal -> bool signal
#
val (>=) : 'a signal -> 'a signal -> bool signal
#
val compare : 'a signal -> 'a signal -> int signal
#
val (==) : 'a signal -> 'a signal -> bool signal
#
val (!=) : 'a signal -> 'a signal -> bool signal
end
#

Combinator specialization

Given an equality function equal and a type t, the functor Make automatically applies the eq parameter of the combinators. The outcome is combinators whose results are signals with values in t.

Basic types are already specialized in the module Special, open this module to use them.

#
module type EqType = sig

Input signature of S.Make

#
type 'a t
#
val equal : 'a t -> 'a t -> bool
end
#
module type S = sig

Output signature of S.Make

#
type 'a v
#
val create : 'a v -> 'a v signal * (?step:step -> 'a v -> unit)
#
val equal : 'a v signal -> 'a v signal -> bool
#
val hold : 'a v -> 'a v event -> 'a v signal
#
val app : ('a -> 'b v) signal -> 'a signal -> 'b v signal
#
val map : ('a -> 'b v) -> 'a signal -> 'b v signal
#
val filter : ('a v -> bool) -> 'a v -> 'a v signal -> 'a v signal
#
val fmap : ('a -> 'b v option) -> 'b v -> 'a signal -> 'b v signal
#
val when_ : bool signal -> 'a v -> 'a v signal -> 'a v signal
#
val dismiss : 'b event -> 'a v -> 'a v signal -> 'a v signal
#
val accum : ('a v -> 'a v) event -> 'a v -> 'a v signal
#
val fold : ('a v -> 'b -> 'a v) -> 'a v -> 'b event -> 'a v signal
#
val merge : ('a v -> 'b -> 'a v) -> 'a v -> 'b signal list -> 'a v signal
#
val switch : 'a v signal signal -> 'a v signal
#
val bind : 'b signal -> ('b -> 'a v signal) -> 'a v signal
#
val fix : 'a v -> ('a v signal -> 'a v signal * 'b) -> 'b
#
val l1 : ('a -> 'b v) -> 'a signal -> 'b v signal
#
val l2 : ('a -> 'b -> 'c v) -> 'a signal -> 'b signal -> 'c v signal
#
val l3 : ('a -> 'b -> 'c -> 'd v) -> 'a signal -> 'b signal -> 'c signal -> 'd v signal
#
val l4 : ('a -> 'b -> 'c -> 'd -> 'e v) -> 'a signal -> 'b signal -> 'c signal -> 'd signal -> 'e v signal
#
val l5 : ('a -> 'b -> 'c -> 'd -> 'e -> 'f v) -> 'a signal -> 'b signal -> 'c signal -> 'd signal -> 'e signal -> 'f v signal
#
val l6 : ('a -> 'b -> 'c -> 'd -> 'e -> 'f -> 'g v) -> 'a signal -> 'b signal -> 'c signal -> 'd signal -> 'e signal -> 'f signal -> 'g v signal
end
#
module Make : functor (Eq : EqType) -> S with type 'a v = 'a Eq.t

Functor specializing the combinators for the given signal value type

#
module Special : sig

Specialization for booleans, integers and floats.

Open this module to use it.

#
module Sb : S with type 'a v = bool

Specialization for booleans.

#
module Si : S with type 'a v = int

Specialization for integers.

#
module Sf : S with type 'a v = float

Specialization for floats.

end
end
#
module Step : sig

Update steps.

Update functions returned by S.create and E.create implicitely create and execute update steps when used without specifying their step argument.

Using explicit step values with these functions gives more control on the time when the update step is perfomed and allows to perform simultaneous primitive signal updates and event occurences. See also the documentation about update steps and simultaneous events.

Steps

#
type t = step

The type for update steps.

#
val create : unit -> step

create () is a new update step.

#
val execute : step -> unit

execute step executes the update step.

Raises Invalid_argument if step was already executed.
end
#

Semantics

The following notations are used to give precise meaning to the combinators. It is important to note that in these semantic descriptions the origin of time t = 0 is always fixed at the time at which the combinator creates the event or the signal and the semantics of the dependents is evaluated relative to this timeline.

We use dt to denote an infinitesimal amount of time.

#

Events

An event is a value with discrete occurrences over time.

The semantic function [] : 'a event -> time -> 'a option gives meaning to an event e by mapping it to a function of time [e] returning Some v whenever the event occurs with value v and None otherwise. We write [e]t the evaluation of this semantic function at time t.

As a shortcut notation we also define <t : 'a event -> 'a option (resp. []<=t) to denote the last occurrence, if any, of an event before (resp. before or at) t. More precisely :

  • [e]<t = [e]t' with t' the greatest t' < t (resp. <=) such that [e]t' <> None.
  • [e]<t = None if there is no such t'.
#

Signals

A signal is a value that varies continuously over time. In contrast to events which occur at specific point in time, a signal has a value at every point in time.

The semantic function [] : 'a signal -> time -> 'a gives meaning to a signal s by mapping it to a function of time [s] that returns its value at a given time. We write [s]t the evaluation of this semantic function at time t.

#

Equality

Most signal combinators have an optional eq parameter that defaults to structural equality. eq specifies the equality function used to detect changes in the value of the resulting signal. This function is needed for the efficient update of signals and to deal correctly with signals that perform side effects.

Given an equality function on a type the combinators can be automatically specialized via a functor.

#

Continuity

Ultimately signal updates depend on primitives updates. Thus a signal can only approximate a real continuous signal. The accuracy of the approximation depends on the variation rate of the real signal and the primitive's update frequency.

#

Basics

#

Primitive events and signals

React doesn't define primitive events and signals, they must be created and updated by the client.

Primitive events are created with E.create. This function returns a new event and an update function that generates an occurrence for the event at the time it is called. The following code creates a primitive integer event x and generates three occurrences with value 1, 2, 3. Those occurrences are printed on stdout by the effectful event pr_x.

open React;;

let x, send_x = E.create ()
let pr_x = E.map print_int x
let () = List.iter send_x [1; 2; 3]

Primitive signals are created with S.create. This function returns a new signal and an update function that sets the signal's value at the time it is called. The following code creates an integer signal x initially set to 1 and updates it three time with values 2, 2, 3. The signal's values are printed on stdout by the effectful signal pr_x. Note that only updates that change the signal's value are printed, hence the program prints 123, not 1223. See the discussion on side effects for more details.

open React;;

let x, set_x = S.create 1
let pr_x = S.map print_int x
let () = List.iter set_x [2; 2; 3]

The clock example shows how a realtime time flow can be defined.

#

Update steps

The E.create and S.create functions return update functions used to generate primitive event occurences and set the value of primitive signals. Upon invocation as in the preceding section these functions immediatly create and invoke an update step. The update step automatically updates events and signals that transitively depend on the updated primitive. The dependents of a signal are updated iff the signal's value changed according to its equality function.

The update functions have an optional step argument. If they are given a concrete step value created with Step.create, then it updates the event or signal but doesn't update its dependencies. It will only do so whenever step is executed with Step.execute. This allows to make primitive event occurences and signal changes simultaneous. See next section for an example.

#

Simultaneous events

Update steps are made under a synchrony hypothesis : the update step takes no time, it is instantenous. Two event occurrences are simultaneous if they occur in the same update step.

In the code below w, x and y will always have simultaneous occurrences. They may have simulatenous occurences with z if send_w and send_z are used with the same update step.

let w, send_w = E.create ()
let x = E.map succ w
let y = E.map succ x
let z, send_z = E.create ()

let () =
  let () = send_w 3 (* w x y occur simultaneously, z doesn't occur *) in
  let step = Step.create () in
  send_w ~step 3;
  send_z ~step 4;
  Step.execute step (* w x z y occur simultaneously *)
#

The update step and thread safety

Primitives are the only mean to drive the reactive system and they are entirely under the control of the client. When the client invokes a primitive's update function without the step argument or when it invokes Step.execute on a step value, React performs an update step.

To ensure correctness in the presence of threads, update steps must be executed in a critical section. Let uset(p) be the set of events and signals that need to be updated whenever the primitive p is updated. Updating two primitives p and p' concurrently is only allowed if uset(p) and uset(p') are disjoint. Otherwise the updates must be properly serialized.

Below, concurrent, updates to x and y must be serialized (or performed on the same step if it makes sense semantically), but z can be updated concurently to both x and y.

open React;;

let x, set_x = S.create 0
let y, send_y = E.create ()
let z, set_z = S.create 0
let max_xy = S.l2 (fun x y -> if x > y then x else y) x (S.hold 0 y)
let succ_z = S.map succ z
#

Side effects

Effectful events and signals perform their side effect exactly once in each update step in which there is an update of at least one of the event or signal it depends on.

Remember that a signal updates in a step iff its equality function determined that the signal value changed. Signal initialization is unconditionally considered as an update.

It is important to keep references on effectful events and signals. Otherwise they may be reclaimed by the garbage collector. The following program prints only a 1.

let x, set_x = S.create 1
let () = ignore (S.map print_int x)
let () = Gc.full_major (); List.iter set_x [2; 2; 3]

#

Lifting

Lifting transforms a regular function to make it act on signals. The combinators S.const and S.app allow to lift functions of arbitrary arity n, but this involves the inefficient creation of n-1 intermediary closure signals. The fixed arity lifting functions are more efficient. For example :

let f x y = x mod y
let fl x y = S.app (S.app ~eq:(==) (S.const f) x) y (* inefficient *)
let fl' x y = S.l2 f x y                            (* efficient *)

Besides, some of Pervasives's functions and operators are already lifted and availables in submodules of S. They can be be opened in specific scopes. For example if you are dealing with float signals you can open S.Float.

open React
open React.S.Float

let f t = sqrt t *. sin t (* f is defined on float signals *)
...
open Pervasives (* back to pervasives floats *)

If you are using OCaml 3.12 or later you can also use the let open construct

let open React.S.Float in
let f t = sqrt t *. sin t in (* f is defined on float signals *)
...
#

Mutual and self reference

Mutual and self reference among time varying values occurs naturally in programs. However a mutually recursive definition of two signals in which both need the value of the other at time t to define their value at time t has no least fixed point. To break this tight loop one signal must depend on the value the other had at time t-dt where dt is an infinitesimal delay.

The fixed point combinators E.fix and S.fix allow to refer to the value an event or signal had an infinitesimal amount of time before. These fixed point combinators act on a function f that takes as argument the infinitesimally delayed event or signal that f itself returns.

In the example below history s returns a signal whose value is the history of s as a list.

let history ?(eq = ( = )) s =
  let push v = function
    | [] -> [ v ]
    | v' :: _ as l when eq v v' -> l
    | l -> v :: l
  in
  let define h =
    let h' = S.l2 push s h in
    h', h'
  in
  S.fix [] define

When a program has infinitesimally delayed values a primitive may trigger more than one update step. For example if a signal s is infinitesimally delayed, then its update in a step c will trigger a new step c' at the end of the step in which the delayed signal of s will have the value s had in c. This means that the recursion occuring between a signal (or event) and its infinitesimally delayed counterpart must be well-founded otherwise this may trigger an infinite number of update steps, like in the following examples.

let start, send_start = E.create ()
let diverge =
  let define e =
    let e' = E.select [e; start] in
    e', e'
  in
  E.fix define

let () = send_start ()        (* diverges *)

let diverge =                 (* diverges *)
  let define s =
    let s' = S.Int.succ s in
    s', s'
  in
  S.fix 0 define

For technical reasons, delayed events and signals (those given to fixing functions) are not allowed to directly depend on each other. Fixed point combinators will raise Invalid_argument if such dependencies are created. This limitation can be circumvented by mapping these values with the identity.

#

Strong stops

Strong stops should only be used on platforms where weak arrays have a strong semantics (i.e. JavaScript). You can safely ignore that section and the strong argument of E.stop and S.stop if that's not the case.

Whenever E.stop and S.stop is called with ~strong:true on a reactive value v, it is first stopped and then it walks over the list prods of events and signals that it depends on and unregisters itself from these ones as a dependent (something that is normally automatically done when v is garbage collected since dependents are stored in a weak array). Then for each element of prod that has no dependents anymore and is not a primitive it stops them aswell and recursively.

A stop call with ~strong:true is more involved. But it allows to prevent memory leaks when used judiciously on the leaves of the reactive system that are no longer used.

Warning. It should be noted that if direct references are kept on an intermediate event or signal of the reactive system it may suddenly stop updating if all its dependents were strongly stopped. In the example below, e1 will never occur:

let e, e_send = E.create ()
let e1 = E.map (fun x -> x + 1) e (* never occurs *)
let () =
  let e2 = E.map (fun x -> x + 1) e1 in
  E.stop ~strong:true e2

This can be side stepped by making an artificial dependency to keep the reference:

let e, e_send = E.create ()
let e1 = E.map (fun x -> x + 1) e (* may still occur *)
let e1_ref = E.map (fun x -> x) e1
let () =
  let e2 = E.map (fun x -> x + 1) e1 in
  E.stop ~strong:true e2
#

Examples

#

Clock

The following program defines a primitive event seconds holding the UNIX time and occuring on every second. An effectful event converts these occurences to local time and prints them on stdout along with an ANSI escape sequence to control the cursor position.

let pr_time t =
  let tm = Unix.localtime t in
  Printf.printf "\x1B[8D%02d:%02d:%02d%!"
    tm.Unix.tm_hour tm.Unix.tm_min tm.Unix.tm_sec

open React;;

let seconds, run =
  let e, send = E.create () in
  let run () =
    while true do send (Unix.gettimeofday ()); Unix.sleep 1 done
  in
  e, run

let printer = E.map pr_time seconds

let () = run ()
end