X-Git-Url: http://git.annexia.org/?p=whenjobs.git;a=blobdiff_plain;f=tools%2Fwhenjobs.pod;fp=tools%2Fwhenjobs.pod;h=fe3041baa830650fa48e3e04ce591ad73a0afbab;hp=b8c76a6c6637f2a8c4bc319032ce4bf864234225;hb=2ce29ff559f9bc36733ab2dde5b657eaa76ea8a6;hpb=7ab4d4728286830f96da8d116c61046c1e4cf83a diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod index b8c76a6..fe3041b 100644 --- a/tools/whenjobs.pod +++ b/tools/whenjobs.pod @@ -592,6 +592,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 @@ -660,6 +691,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. @@ -687,6 +734,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