X-Git-Url: http://git.annexia.org/?p=whenjobs.git;a=blobdiff_plain;f=tools%2Fwhenjobs.pod;h=25dff409786935c0d1730aed6daeca34b79374c1;hp=a27285541b48ab70ea2e7318a7a91cd466b37a4c;hb=82c14058a0252e953cae3bd2f1fc3fe00746d173;hpb=0c9faf57f9239b0fe1c0b46353d222bb4cf5cd74;ds=sidebyside

diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod
index a272855..25dff40 100644
--- a/tools/whenjobs.pod
+++ b/tools/whenjobs.pod
@@ -149,13 +149,6 @@ source, eg:
 
  whenjobs --lib $builddir/lib -e
 
-=item B<--start> "job name"
-
-Start the job immediately and unconditionally.
-
-This runs the job even if its normal preconditions are not met.  This
-may cause unexpected results, so use with caution.
-
 =item B<--set> variable value
 
 =item B<--type> bool|int|float|string|unit
@@ -176,6 +169,13 @@ variable when setting it by adding the optional I<--type> parameter:
 See the discussion of variable types in the L</REFERENCE> section
 below.
 
+=item B<--start> "job name"
+
+Start the job immediately and unconditionally.
+
+This runs the job even if its normal preconditions are not met.  This
+may cause unexpected results, so use with caution.
+
 =item B<--upload>
 
 Compile the jobs script and upload it to the daemon, without editing.
@@ -403,6 +403,11 @@ that it had last time this when-job ran.
 
 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
@@ -582,7 +587,7 @@ reloaded.
 
 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
@@ -592,6 +597,37 @@ this example:
    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
@@ -621,7 +657,8 @@ defined below.
 =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.
@@ -659,6 +696,22 @@ Here are some examples of using the mailto function:
    # 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.
@@ -686,6 +739,24 @@ Set variable I<name> to the floating point value I<f>.
 
 =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