Scheduling of every-jobs.

[whenjobs.git] / lib / whenutils.mli

diff --git a/lib/whenutils.mli b/lib/whenutils.mli
index b2a8878..2d5bbfa 100644 (file)
--- a/lib/whenutils.mli
+++ b/lib/whenutils.mli
@@ -81,6 +81,9 @@ module StringSet : sig
 end
 (** A set of strings. *)
 
+val filter_map : ('a -> 'b option) -> 'a list -> 'b list
+(** Filter + map. *)
+
 type whenexpr =
   | Expr_bool of bool                   (** A boolean constant. *)
   | Expr_str of string                  (** A string constant. *)
@@ -163,3 +166,38 @@ val job_evaluate : job -> variables -> bool * job
     possibly-updated [job] structure.
 
     This is a no-op for 'every' jobs. *)
+
+val next_periodexpr : float -> periodexpr -> float
+(** [next_periodexpr t period] returns the earliest event of [period]
+    strictly after time [t].
+
+    Visualising periods as repeated events on a timeline, this
+    returns [t']:
+
+    {v
+    events:  ---+---------+---------+---------+---------+---------+-----
+    times:          t     t'
+    }
+
+    Note that [periodexpr] events are not necessarily regular.
+    eg. The start of a month is not a fixed number of seconds
+    after the start of the previous month.  'Epoch' refers
+    to the Unix Epoch (ie. 1970-01-01 00:00:00 UTC).
+
+    If [period = Every_seconds i] then events are when
+    [t' mod i == 0] when t' is the number of seconds since
+    the Epoch.  This returns the next t' > t.
+
+    If [period = Every_days i] then events happen at
+    midnight UTC every [i] days since the Epoch.
+    This returns the next midnight > t.
+
+    If [period = Every_months i] then events happen at
+    midnight UTC on the 1st day of the month every [i] months
+    since the Epoch.  This returns midnight on the
+    1st day of the next month > t.
+
+    If [period = Every_years i] then events happen at
+    midnight UTC on the 1st day of the year when
+    [(y - 1970) mod i == 0].  This returns midnight on the
+    1st day of the next year > t. *)