incremental v0.12.0 · OCaml Package

type t

val sexp_of_t : t -> Ppx_sexp_conv_lib.Sexp.t

val default_timing_wheel_config : Core_kernel.Timing_wheel_ns.Config.t

The default timing-wheel configuration, with one millisecond precision with alarms up to 30 days in the future.

val create : 
  ?timing_wheel_config:Core_kernel.Timing_wheel_ns.Config.t ->
  start:Core_kernel.Int63.t ->
  unit ->
  t

val alarm_precision : t -> Core_kernel.Time_ns.Span.t

The alarm_precision of the underlying timing wheel.

val timing_wheel_length : t -> int

val now : t -> Core_kernel.Int63.t

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

val watch_now : t -> Core_kernel.Int63.t incremental

watch_now t returns an incremental that tracks the current time.

val advance_clock : t -> to_:Core_kernel.Int63.t -> unit

advance_clock t ~to_ moves incremental's clock forward to to_. advance_clock raises 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 at : t -> Core_kernel.Int63.t -> Before_or_after.t incremental

at time returns an incremental that is Before when now () <= time and After when now () >= time + alarm_precision. When now () is between time and time + alarm_precision, at time might be Before or After, due to the fundamental imprecision of the timing wheel. One is guaranteed that an at never becomes After too early, but it may become After up to alarm_precision late.

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

val after : t -> Core_kernel.Time_ns.Span.t -> Before_or_after.t incremental

val at_intervals : t -> Core_kernel.Time_ns.Span.t -> unit incremental

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

Time_ns.next_multiple ~base ~after ~interval

where base is now () when at_intervals was called and after is the current now (). As with at, at_intervals might fire up to alarm_precision late.

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 : 
  t ->
  init:'a ->
  (Core_kernel.Int63.t * 'a) list ->
  'a incremental

step_function ~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 the clock's time passes ti. As with at, the steps might take effect up to alarm_precision late.

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 snapshot : 
  t ->
  'a incremental ->
  at:Core_kernel.Int63.t ->
  before:'a ->
  'a incremental Core_kernel.Or_error.t

snapshot 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 after which the time passes at. snapshot causes value_at to be necessary during the first stabilization after which time passes at 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 (), because it is impossible to take the snapshot because the time has already passed.

package incremental