incremental
  1. Overview
  2. Docs
package incremental
Legend:
Library
Module
Module type
Parameter
Class
Class type

Incremental has a timing-wheel-based clock, and lets one build incremental values that change as its time passes. One must explicitly call advance_clock to change incremental's clock; there is no implicit call based on the passage of time.

type 'w t
val sexp_of_t : ('w -> Sexplib0.Sexp.t) -> 'w t -> Sexplib0.Sexp.t
val default_timing_wheel_config : Timing_wheel.Config.t

The default timing-wheel configuration, with one millisecond precision, and alarms allowed arbitrarily far in the future.

val create : 'w State.t -> ?timing_wheel_config:Timing_wheel.Config.t -> start:Core.Int63.t -> unit -> 'w t
val alarm_precision : _ t -> Core.Time_ns.Span.t

The alarm_precision of the underlying timing wheel.

val state : 'w t -> 'w State.t
val timing_wheel_length : _ t -> int
val now : _ t -> Core.Int63.t

now t returns the current time of incremental's clock.

val watch_now : 'w t -> (Core.Int63.t, 'w) incremental

watch_now t returns an incremental that tracks the current time.

val advance_clock : _ t -> to_:Core.Int63.t -> unit

advance_clock t ~to_ moves incremental's clock forward to to_. advance_clock is a no-op if to_ < now t. As with Var.set, the effect of advance_clock is not seen on incremental values until the next stabilization. Unlike Var.set, calling advance_clock during stabilization raises.

In certain pathological cases, advance_clock can raise due to it detecting a cycle in the incremental graph.

val advance_clock_by : _ t -> Core.Time_ns.Span.t -> unit

advance_clock_by t span = advance_clock t ~to_:(Time_ns.add (now t) span)

at t time returns an incremental that is Before when now t < time and After when now t >= time.

after t span is at t (Time_ns.add (now t) span).

val at_intervals : 'w t -> Core.Time_ns.Span.t -> (unit, 'w) incremental

at_intervals t interval returns an incremental whose value changes at time intervals of the form:

Time_ns.next_multiple ~base ~after ~interval

where base is now t when at_intervals was called and after is the current now t.

at_intervals raises if interval < alarm_precision. The unit t that at_intervals returns has its cutoff set to Cutoff.never, so that although its value is always (), incrementals that depend on it will refire each time it is set. The result of at_intervals remains alive and is updated until the left-hand side of its defining bind changes, at which point it becomes invalid.

val step_function : 'w t -> init:'a -> (Core.Int63.t * 'a) list -> ('a, 'w) incremental

step_function t ~init [(t1, v1); ...; (tn, vn)] returns an incremental whose initial value is init and takes on the values v1, ..., vn in sequence taking on the value vi when now t >= ti.

It is possible for vi to be skipped if time advances from t(i-1) to some time greater than t(i+1).

The times must be in nondecreasing order, i.e. step_function raises if for some i < j, ti > tj.

val incremental_step_function : 'w t -> ('a Step_function.t, 'w) incremental -> ('a, 'w) incremental

incremental_step_function t i returns an incremental whose value is Step_function.value f ~at:(now t), where f is the value of i.

val snapshot : 'w t -> ('a, 'w) incremental -> at:Core.Int63.t -> before:'a -> ('a, 'w) incremental Core.Or_error.t

snapshot t value_at ~at ~before returns an incremental whose value is before before at and whose value is frozen to the value of value_at during the first stabilization in which the time passes at. snapshot causes value_at to be necessary during that stabilization even if the snapshot node itself is not necessary, but not thereafter (although of course value_at could remain necessary for other reaspons). The result of snapshot will only be invalidated if value_at is invalid at the moment of the snapshot.

snapshot returns Error if at < now t, because it is impossible to take the snapshot because the time has already passed.