X-Git-Url: http://git.annexia.org/?p=whenjobs.git;a=blobdiff_plain;f=tools%2Fwhenjobs.pod;h=85da381eaa671a288593e451dc1164fb77b0e5be;hp=a27285541b48ab70ea2e7318a7a91cd466b37a4c;hb=7724a64945c4f485780ed052de17793287e1935b;hpb=0c9faf57f9239b0fe1c0b46353d222bb4cf5cd74 diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod index a272855..85da381 100644 --- a/tools/whenjobs.pod +++ b/tools/whenjobs.pod @@ -14,7 +14,7 @@ Editing the jobs script: Get and set variables: whenjobs --get variable - whenjobs --set variable value [--type bool|int|float|string] + whenjobs --set variable=value [variable=value ...] whenjobs --variables Start and stop the per-user daemon: @@ -29,6 +29,7 @@ Examine running jobs: whenjobs --jobs whenjobs --cancel serial whenjobs --start "name" + whenjobs --tail serial =head1 DESCRIPTION @@ -42,7 +43,7 @@ Periodic jobs are written like this: << # Get the current load average. load=`awk '{print $1}' /proc/loadavg` - whenjobs --set load $load --type float + whenjobs --set --type float load=$load >> When-statements let you create jobs that run based on variables set @@ -79,7 +80,7 @@ command line tool to examine and set variables: $ whenjobs --variables load=0.9 - $ whenjobs --set cat sushi + $ whenjobs --set cat=sushi $ whenjobs --get cat sushi @@ -126,6 +127,11 @@ C is used. Print the value of a variable. +=item B<--job-names> + +List the names of all loaded jobs (whether they are running or not). +Use I<--jobs> to list running jobs. + =item B<--jobs> List all running jobs. @@ -149,14 +155,7 @@ 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<--set> variable=value [variable=value ...] =item B<--type> bool|int|float|string|unit @@ -164,18 +163,56 @@ I<--set> sets the variable named C to the new C. The variable is created if it does not already exist. Note that setting a variable can cause jobs to run immediately. -To unset a variable, set it to the empty string: +To unset a variable, set it to the empty string like this: - whenjobs --set var "" + whenjobs --set var= By default variables are strings. You can also set the type of a -variable when setting it by adding the optional I<--type> parameter: +variable when setting it by adding the optional I<--type> parameter. +The I<--type> parameter should come I the variable +declaration, like this: - whenjobs --set free_space 10000 --type int + whenjobs --set --type int free_space=10000 See the discussion of variable types in the L section below. +You can set multiple variables. When setting multiple variables in a +single command, the values are all changed in a single atomic +operation. + + whenjobs --set cat=sushi food=fish + +When using I<--type> and multiple variables, the type changes the +remaining command line parameters until the next I<--type>, eg: + + whenjobs --set cat=sushi --type float weight=3.5 --type string food=fish + +(C and C are strings, and C is a float). + +=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<--tail> serial + +Tail the output of the running job identified by its serial number. +Use the I<--jobs> flag to get a list of running jobs. + +=item B<--test> variable=value [variable=value ...] + +This works the same way as the I<--set> option, but the difference is +that the variables are not set. Instead, it lists out the jobs that +I run, I the variables were updated to these new values. + +The variables are not actually updated, and the jobs are not actually +run. + +The output is a list of job names that would run. + =item B<--upload> Compile the jobs script and upload it to the daemon, without editing. @@ -403,6 +440,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 for jobs that +are explicitly named. If you find that jobs using C, C +etc are running unnecessarily when the jobs file is edited or +uploaded, try giving the jobs an explicit name. + =item B I If the named variable has changed since this job last ran, then this @@ -582,7 +624,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 functions as in @@ -592,6 +634,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
 function is called.
+This function may decide not to run the job (by returning C).
+
+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 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 struct, defined
+below.  It should return a boolean: C if the job should run, and
+C if the job should not run.
+
+Note that a fresh serial number (see L) 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 +694,8 @@ defined below.
 =item B [I<~only_on_failure:true>]
 [I<~from:from_address>] I I
 
-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 +733,22 @@ Here are some examples of using the mailto function:
    # do something
  >>
 
+=item B I
+
+This built-in pre function ensures that a maximum of I instances of
+the job are running.
+
+It checks the list of running jobs, and if I or more instances are
+already running, then it returns C, which ensures that the new
+job is not started.
+
+=item B 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 I I
 
 Set variable I to the string.
@@ -686,6 +776,24 @@ Set variable I to the floating point value I.
 
 =over 4
 
+=item B
+
+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
 
 This structure is passed to post functions.  It has the following