Events provide variants of run_at and run_after with the ability to abort or reschedule an event that hasn't yet happened. Once an event happens or is aborted, Async doesn't use any space for tracking it.
include sig ... endval sexp_of_t :
('a -> Sexplib.Sexp.t) ->
('h -> Sexplib.Sexp.t) ->
('a, 'h) t ->
Sexplib.Sexp.ttype t_unit = (unit, unit) tinclude sig ... endval sexp_of_t_unit : t_unit -> Sexplib.Sexp.tinclude Core_kernel.Invariant.S2 with type ('a, 'b) t := ('a, 'b) tval invariant :
'a Base__.Invariant_intf.inv ->
'b Base__.Invariant_intf.inv ->
('a, 'b) t Base__.Invariant_intf.invval scheduled_at : (_, _) t -> Core.Time.tmodule Status : sig ... endIf 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.
val run_at : Core.Time.t -> ('z -> 'h) -> 'z -> (_, 'h) tLet 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.
val run_after : Core.Time.Span.t -> ('z -> 'h) -> 'z -> (_, 'h) tmodule Abort_result = Async_kernel.Time_source.Event.Abort_resultval abort : ('a, 'h) t -> 'a -> ('a, 'h) Abort_result.tabort t changes status t to Aborted and returns Ok, unless t previously happened or was previously aborted.
val abort_exn : ('a, 'h) t -> 'a -> unitabort_exn t a returns unit if abort t a = `Ok, and otherwise raises.
val abort_if_possible : ('a, _) t -> 'a -> unitabort_if_possible t a = ignore (abort t a).
module Fired = Async_kernel.Time_source.Event.Firedval fired : ('a, 'h) t -> ('a, 'h) Fired.t Async_kernel.Clock_intf.Deferred.tmodule Reschedule_result = Async_kernel.Time_source.Event.Reschedule_resultval reschedule_at : ('a, 'h) t -> Core.Time.t -> ('a, 'h) Reschedule_result.treschedule_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.
val reschedule_after :
('a, 'h) t ->
Core.Time.Span.t ->
('a, 'h) Reschedule_result.tval at : Core.Time.t -> (_, unit) tat time is run_at time ignore (). after time is run_after time ignore ().
You should generally prefer to use the run_* functions, which allow one 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.
val after : Core.Time.Span.t -> (_, unit) t