Module Timing_wheel_ns

create ~config ~start creates a new timing wheel with current time start. create raises if start < Time.epoch. For a fixed level_bits, a smaller (i.e. more precise) alarm_precision decreases the representable range of times/keys and increases the constant factor for advance_clock.

Accessors

One can think of a timing wheel as a set of alarms. Here are various container functions along those lines.

interval_num t time returns the number of the interval that time is in, where 0 is the interval that starts at Time.epoch. interval_num raises if Time.( < ) time Time.epoch.

now_interval_num t equals interval_num t (now t).

interval_num_start t n is the start of the n'th interval in t, i.e. n * alarm_precision t after the epoch.

interval_start t time is the start of the half-open interval containing time, i.e.:

        interval_num_start t (interval_num t time)
      

interval_start raises in the same cases that interval_num does.

advance_clock t ~to_ ~handle_fired advances t's clock to to_. It fires and removes all alarms a in t with Time.(<) (Alarm.at t a) (interval_start t to_), applying handle_fired to each such a.

If to_ <= now t, then advance_clock does nothing.

advance_clock fails if to_ is too far in the future to represent.

Behavior is unspecified if handle_fired accesses t in any way other than Alarm functions.

fire_past_alarms t ~handle_fired fires and removes all alarms a in t with Time.( <= ) (Alarm.at t a) (now t), applying handle_fired to each such a.

fire_past_alarms visits all alarms in interval now_interval_num, to check their Alarm.at.

Behavior is unspecified if handle_fired accesses t in any way other than Alarm functions.

alarm_upper_bound t returns the upper bound on an at that can be supplied to add. alarm_upper_bound t is not constant; its value increases as now t increases.

add t ~at a adds a new value a to t and returns an alarm that can later be supplied to remove the alarm from t. add raises if interval_num t at < now_interval_num t || at >= alarm_upper_bound t.

add_at_interval_num t ~at a is equivalent to add t ~at:(interval_num_start t at) a.

remove t alarm removes alarm from t. remove raises if not (mem t alarm).

reschedule t alarm ~at mutates alarm so that it will fire at at, i.e. so that Alarm.at t alarm = at. reschedule raises if not (mem t alarm) or if at is an invalid time for t, in the same situations that add raises.

reschedule_at_interval_num t alarm ~at is equivalent to:

        reschedule t alarm ~at:(interval_num_start t at)
      

clear t removes all alarms from t.

next_alarm_fires_at t returns the minimum time to which the clock can be advanced such that an alarm will fire, or None if t has no alarms. If next_alarm_fires_at t = Some next, then for the minimum alarm time min that occurs in t, it is guaranteed that: next - alarm_precision t <= min < next.

next_alarm_fires_at_exn is the same as next_alarm_fires_at, except that it raises if is_empty t.