If the when-job has not run yet, then this returns C<"">.
+Job state is preserved across file reloads, but I<only> for jobs that
+are explicitly named. If you find that jobs using C<prev>, C<changes>
+etc are running unnecessarily when the jobs file is edited or
+uploaded, try giving the jobs an explicit name.
+
=item B<changes> I<variable>
If the named variable has changed since this job last ran, then this
Variables are created when they are referenced, and until set they
have the value empty string (just like the shell). Across file
-reloads, the previous values of variables is preserved.
+reloads, the previous values of variables are preserved.
To initialize a variable to a known value when the jobs file is
loaded, call one of the C<Whentools.set_variable*> functions as in
Whentools.set_variable "name" "Richard";
Whentools.set_variable_int "counter" 0
+=head3 PRE FUNCTIONS
+
+Before a job runs, you can arrange that a C<pre> function is called.
+This function may decide not to run the job (by returning C<false>).
+
+One use for this is to prevent a particular job from running if there
+is already an instance of the same job running:
+
+ job "only one"
+ pre (Whentools.one ())
+ every 10 seconds :
+ <<
+ # Takes longer than 10 seconds to run, but 'Whentools.one ()'
+ # will ensure only one is ever running.
+ sleep 11
+ >>
+
+When using pre functions, jobs must be given an explicit name, ie.
+you must use the C<job> statement.
+
+A number of pre functions are available in the library; see below.
+
+You can also write your own post functions (in OCaml). The function
+is passed one argument which is a C<Whentools.preinfo> struct, defined
+below. It should return a boolean: C<true> if the job should run, and
+C<false> if the job should not run.
+
+Note that a fresh serial number (see L</JOBSERIAL>) is assigned to
+each run, whether or not the job actually runs because of
+preconditions.
+
=head3 POST FUNCTIONS
After a job runs, you can control what happens to its output by
=item B<Whentools.mailto> [I<~only_on_failure:true>]
[I<~from:from_address>] I<email_address> I<result>
-Send the result of the script by email to the given email address.
+This built-in post function sends the result of the script by email to
+the given email address.
If the optional C<~only_on_failure:true> flag is set, then it is only
sent out if the script failed.
# do something
>>
+=item B<Whentools.max> I<n>
+
+This built-in pre function ensures that a maximum of I<n> instances of
+the job are running.
+
+It checks the list of running jobs, and if I<n> or more instances are
+already running, then it returns C<false>, which ensures that the new
+job is not started.
+
+=item B<Whentools.one> I<()>
+
+This built-in pre function ensures that only one instance of the job
+is running. It is the same as calling:
+
+ Whentools.max 1
+
=item B<Whentools.set_variable> I<name> I<string>
Set variable I<name> to the string.
=over 4
+=item B<Whentools.preinfo>
+
+This structure is passed to pre functions. It has the following
+fields:
+
+ type preinfo = {
+ pi_job_name : string; # Job name.
+ pi_serial : Big_int.big_int; # Job serial number.
+ pi_variables : (string * variable) list; # Variables set in job.
+ pi_running : preinfo_running_job list; # List of running jobs.
+ }
+ and preinfo_running_job = {
+ pirun_job_name : string; # Running job name.
+ pirun_serial : Big_int.big_int; # Running job serial number.
+ pirun_start_time : float; # Running job start time.
+ pirun_pid : int; # Running job process ID.
+ }
+
=item B<Whentools.result>
This structure is passed to post functions. It has the following
git.annexia.org / whenjobs.git / blobdiff