Cosmetic changes to the help output and man page.

[whenjobs.git] / tools / whenjobs.pod

diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod
index a272855..25dff40 100644 (file)
--- a/tools/whenjobs.pod
+++ b/tools/whenjobs.pod
@@ -149,13 +149,6 @@ source, eg:
 
  whenjobs --lib $builddir/lib -e
 
 
  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
 =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.
 
 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.
 =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<"">.
 
 
 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
 =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
 
 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
 
 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
 
    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
 =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>
 
 =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.
 
 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
  >>
 
    # 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.
 =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
 
 
 =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
 =item B<Whentools.result>
 
 This structure is passed to post functions.  It has the following