incr_map v0.10.0 · OCaml Package

type 'a t

include sig ... end

val sexp_of_t : ('a -> Sexplib.Sexp.t) -> 'a t -> Sexplib.Sexp.t

val create : 
  ?on_observability_change:(is_now_observable:bool -> unit) ->
  (unit -> 'a) ->
  'a t

let t = create ?on_observability_change callback creates a new expert node.

on_observability_change, if given, is called whenever the node becomes observable or unobservable (with alternating value for is_now_observable, starting at true the first time the node becomes observable). This callback could run multiple times per stabilization. It should not change the incremental graph.

callback is called if any dependency of t has changed since it was last called, or if the set of dependencies has changed. The callback will only run when all the dependencies are up-to-date, and inside the callback, you can safely call Dependency.value on your dependencies, as well as call all the functions below on the parent nodes. Any behavior that works on all incremental nodes (cutoff, invalidation, debug info etc) also work on t.

val watch : 'a t -> 'a incremental

watch t allows you to plug t in the rest of the incremental graph, but it's also useful to set a cutoff function, debug info etc.

val make_stale : _ t -> unit

Calling make_stale t ensures that incremental will recompute t before anyone reads its value. t may not fire though, if it never becomes necessary. This is intended to be called only from a child of t. Along with a well chosen cutoff function, it allows to choose which parents should fire.

val invalidate : _ t -> unit

invalidate t makes t invalid, as if its surrounding bind had changed. This is intended to be called only from a child of t.

val add_dependency : _ t -> _ Dependency.t -> unit

add_dependency t dep makes t depend on the child incremental in the dep. If dep is already used to link the child incremental to another parent, an exception is raised.

This is intended to be called either outside of stabilization, or right after creating t, or from a child of t (and in that case, as a consequence t must be necessary).

The on_change callback of dep will be fired when t becomes observable, or immediately, or whenever the child changes as long as t is observable. When this function is called due to observability changes, the callback may fire several times in the same stabilization, so it should be idempotent. The callback must not change the incremental graph, particularly not the dependencies of t.

All the on_change callbacks are guaranteed to be run before the callback of create is run.

val remove_dependency : _ t -> _ Dependency.t -> unit

remove_dependency t dep can only be called from a child of t.

package incr_map