2 * Copyright (C) 2012 Red Hat Inc.
4 * This program is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation; either version 2 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License along
15 * with this program; if not, write to the Free Software Foundation, Inc.,
16 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19 (** When- and every-expression definition and evaluation, variables
23 | Expr_unit (** Unit constant. *)
24 | Expr_bool of bool (** A boolean constant. *)
25 | Expr_str of string (** A string constant. *)
26 | Expr_int of Big_int.big_int (** An integer constant. *)
27 | Expr_float of float (** A float constant. *)
28 | Expr_var of string (** A variable name. *)
29 | Expr_and of whenexpr * whenexpr (** && *)
30 | Expr_or of whenexpr * whenexpr (** || *)
31 | Expr_lt of whenexpr * whenexpr (** < *)
32 | Expr_le of whenexpr * whenexpr (** <= *)
33 | Expr_eq of whenexpr * whenexpr (** == *)
34 | Expr_ge of whenexpr * whenexpr (** >= *)
35 | Expr_gt of whenexpr * whenexpr (** > *)
36 | Expr_not of whenexpr (** boolean not *)
37 | Expr_add of whenexpr * whenexpr (** arithmetic addition or string cat *)
38 | Expr_sub of whenexpr * whenexpr (** arithmetic subtraction *)
39 | Expr_mul of whenexpr * whenexpr (** arithmetic multiplication *)
40 | Expr_div of whenexpr * whenexpr (** arithmetic division *)
41 | Expr_mod of whenexpr * whenexpr (** arithmetic modulo *)
42 | Expr_len of whenexpr (** length *)
43 | Expr_changes of string (** changes var *)
44 | Expr_increases of string (** increases var *)
45 | Expr_decreases of string (** decreases var *)
46 | Expr_prev of string (** prev var *)
47 | Expr_reloaded (** reloaded () *)
48 (** Internal type used to represent 'when' expressions. *)
51 | Every_seconds of int
55 (** Internal type used to represent 'every' expressions. *)
58 sh_loc : Camlp4.PreCast.Loc.t;
61 (** A shell script. *)
67 | T_int of Big_int.big_int
69 (** Typed variable (see also [whenproto.x]) *)
71 val string_of_variable : variable -> string
73 val variable_of_rpc : Whenproto_aux.variable -> variable
74 val rpc_of_variable : variable -> Whenproto_aux.variable
76 type variables = variable Whenutils.StringMap.t
77 (** A set of variables. *)
80 pi_job_name : string; (** Job name. *)
81 pi_serial : Big_int.big_int; (** Job serial number. *)
82 pi_variables : (string * variable) list; (** Variables set in job. *)
83 pi_running : preinfo_running_job list; (** List of running jobs. *)
85 and preinfo_running_job = {
86 pirun_job_name : string; (** Running job name. *)
87 pirun_serial : Big_int.big_int; (** Running job serial number. *)
88 pirun_start_time : float; (** Running job start time. *)
89 pirun_pid : int; (** Running job process ID. *)
91 (** Information available to pre function before the job runs. *)
94 res_job_name : string; (** Job name. *)
95 res_serial : Big_int.big_int; (** Job serial number. *)
96 res_code : int; (** Return code from the script. *)
97 res_tmpdir : string; (** Temporary directory. *)
98 res_output : string; (** Filename of output from job. *)
99 res_start_time : float; (** When the job started. *)
101 (** Result of the run of a job. *)
103 type pre = preinfo -> bool
104 type post = result -> unit
105 (** Pre and post functions. *)
108 | When_job of whenexpr (** when ... : << >> *)
109 | Every_job of periodexpr (** every ... : << >> *)
112 job_loc : Camlp4.PreCast.Loc.t;
114 job_pre : pre option;
115 job_post : post option;
117 job_script : shell_script;
121 val expr_of_ast : Camlp4.PreCast.Ast.Loc.t -> Camlp4.PreCast.Ast.expr -> whenexpr
122 (** Convert OCaml AST to an expression. Since OCaml ASTs are much
123 more general than the expressions we can use, this can raise
124 [Invalid_argument] in many different situations. *)
126 val string_of_whenexpr : whenexpr -> string
127 (** Pretty-print an expression to a string. *)
129 val string_of_periodexpr : periodexpr -> string
130 (** Pretty-print a period expression to a string. *)
132 val dependencies_of_whenexpr : whenexpr -> string list
133 (** Return list of variables that an expression depends on. This is
134 used to work out when an expression needs to be reevaluated. *)
136 val dependencies_of_job : job -> string list
137 (** Which variables does this job depend on? *)
139 val eval_whenexpr : variables -> variables option -> bool -> whenexpr -> variable
140 val eval_whenexpr_as_bool : variables -> variables option -> bool -> whenexpr -> bool
141 (** [eval_whenexpr variables prev_variables onload expr] is the
142 evaluation function for when expressions. It full evaluates
143 [expr], returning its typed value. It can also throw exceptions
144 (at least [Invalid_argument] and [Failure]).
146 [eval_whenexpr_as_bool] is the same but it forces the returned
147 value to be a boolean.
149 The other parameters represent the current and past state:
151 [variables] is the current set of variables and their values.
153 [prev_variables] is the set of variables from the previous
154 run. It is used to implement {i prev}, {i changes} etc operators.
155 This can be [None], meaning there is no previous state.
157 [onload] is used to implement the {i reloaded} operator. It is
158 true if the file is being reloaded, and false otherwise. *)
160 val next_periodexpr : float -> periodexpr -> float
161 (** [next_periodexpr t period] returns the earliest event of [period]
162 strictly after time [t].
164 Visualising periods as repeated events on a timeline, this
168 events: ---+---------+---------+---------+---------+---------+-----
172 Note that [periodexpr] events are not necessarily regular.
173 eg. The start of a month is not a fixed number of seconds
174 after the start of the previous month. 'Epoch' refers
175 to the Unix Epoch (ie. 1970-01-01 00:00:00 UTC).
177 If [period = Every_seconds i] then events are when
178 [t' mod i == 0] when t' is the number of seconds since
179 the Epoch. This returns the next t' > t.
181 If [period = Every_days i] then events happen at
182 midnight UTC every [i] days since the Epoch.
183 This returns the next midnight > t.
185 If [period = Every_months i] then events happen at
186 midnight UTC on the 1st day of the month every [i] months
187 since the Epoch. This returns midnight on the
188 1st day of the next month > t.
190 If [period = Every_years i] then events happen at
191 midnight UTC on the 1st day of the year when
192 [(y - 1970) mod i == 0]. This returns midnight on the
193 1st day of the next year > t. *)
195 val check_valid_variable_name : string -> unit
196 (** Check that [name] is a valid variable name that users are permitted
197 to set, and raise [Failure] if it is not. *)