package async_kernel

If status returns Scheduled_at time, it is possible that time < Time.now () if Async's scheduler hasn't yet gotten the chance to update its clock, e.g., due to user jobs running.

Let t = run_at time f z. At time, this runs f z and transitions status t to Happened h, where h is result of f z.

More precisely, at time, provided abort t a has not previously been called, this will call f z, with the guarantee that status t = Scheduled_at time. If f z returns h and did not call abort t a, then status t becomes Happened h. If f z calls abort t a, then the result of f is ignored, and status t is Aborted a.

If f z raises, then status t does not transition and remains Scheduled_at time, and the exception is sent to the monitor in effect when run_at was called.

abort t changes status t to Aborted and returns Ok, unless t previously happened or was previously aborted.

abort_exn t a returns unit if abort t a = `Ok, and otherwise raises.

abort_if_possible t a = ignore (abort t a).

reschedule_at t and reschedule_after t change the time that t will fire, if possible, and if not, give a reason why. Like run_at, if the requested time is in the past, the event will be scheduled to run immediately. If reschedule_at t time = Ok, then subsequently scheduled_at t = time.

at time is run_at time ignore (). after time is run_after time ignore ().

You should generally prefer to use the run_* functions, which allow you to synchronously update state via a user-supplied function when the event transitions to Happened. That is, there is an important difference between:

let t = run_at time f () 

and:

let t = at time in
fired t
>>> function
| Happened () -> f ()
| Aborted () -> () 

With run_at, if status t = Happened, one knows that f has run. With at and fired, one does not know whether f has yet run; it may still be scheduled to run. Thus, with at and fired, it is easy to introduce a race. For example, consider these two code snippets:

let t = Event.after (sec 2.) in
upon (Event.fired t) (function
  | Aborted () -> ()
  | Happened () -> printf "Timer fired");
upon deferred_event (fun () ->
  match Event.abort t () with
  | Ok -> printf "Event occurred"
  | Previously_aborted () -> assert false
  | Previously_happened () -> printf "Event occurred after timer fired"); 

let t = Event.run_after (sec 2.) printf "Timer fired" in
upon deferred_event (fun () ->
  match Event.abort t () with
  | Ok -> printf "Event occurred"
  | Previously_aborted () -> assert false
  | Previously_happened () -> printf "Event occurred after timer fired"); 

In both snippets, if Event.abort returns Ok, "Timer fired" is never printed. However, the first snippet might print "Event occurred after timer fired" and then "Timer fired". This confused ordering cannot happen with Event.run_after.