Note that mailto is a post function.

[whenjobs.git] / tools / whenjobs.pod

diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod
index fd0a6e7..b8c76a6 100644 (file)
--- a/tools/whenjobs.pod
+++ b/tools/whenjobs.pod
@@ -24,6 +24,12 @@ Start and stop the per-user daemon:
  whenjobs --daemon-status
  whenjobs --daemon-restart
 
  whenjobs --daemon-status
  whenjobs --daemon-restart
 

+Examine running jobs:
+
+ whenjobs --jobs
+ whenjobs --cancel serial
+ whenjobs --start "name"
+

 =head1 DESCRIPTION
 
 Whenjobs is a powerful but simple replacement for cron.  It lets you
 =head1 DESCRIPTION
 
 Whenjobs is a powerful but simple replacement for cron.  It lets you


@@ -83,6 +89,14 @@ The act of setting a variable (using I<--set>) can trigger jobs to run.
 
 =over 4
 
 
 =over 4
 

+=item B<--cancel> serial
+
+Cancel the job with the given serial number.
+
+Use I<--jobs> to list running jobs along with their serial numbers.
+The serial number is also available in the job script (as
+C<$JOBSERIAL>) and in the log file.
+

 =item B<--daemon-start>
 
 =item B<--daemon-stop>
 =item B<--daemon-start>
 
 =item B<--daemon-stop>


@@ -112,6 +126,13 @@ C<vi> is used.
 
 Print the value of a variable.
 
 
 Print the value of a variable.
 

+=item B<--jobs>
+
+List all running jobs.
+
+Note that it is possible for the same job to be running more than once
+(for example, a periodic job that takes longer than the period to run).
+

 =item B<-l>
 
 =item B<--list>
 =item B<-l>
 
 =item B<--list>


@@ -128,6 +149,13 @@ 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


@@ -520,7 +548,7 @@ environment variable.
 As well as simple "every" and "when" expressions, advanced users may
 want to use arbitrary OCaml expressions, functions, etc in the jobs
 script.  These are useful for factoring common code or strings, for
 As well as simple "every" and "when" expressions, advanced users may
 want to use arbitrary OCaml expressions, functions, etc in the jobs
 script.  These are useful for factoring common code or strings, for

-setting the initial values of variables, or for defining cleanup
+setting the initial values of variables, or for defining pre and post

 functions.
 
 A simple example of an OCaml expression is:
 functions.
 
 A simple example of an OCaml expression is:


@@ -554,7 +582,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


@@ -564,23 +592,23 @@ 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 CLEANUP FUNCTIONS
+=head3 POST FUNCTIONS

 
 After a job runs, you can control what happens to its output by
 
 After a job runs, you can control what happens to its output by

-writing a cleanup function.  To write a cleanup function you have to
-name the job (ie. have an explicit C<job> statement).  Put C<cleanup ...>
+writing a C<post> function.  To write a post function you have to
+name the job (ie. have an explicit C<job> statement).  Put C<post ...>

 after the job name like this:
 
  job "poll source"
 after the job name like this:
 
  job "poll source"

- cleanup (Whentools.mailto "you@example.com")
+ post (Whentools.mailto "you@example.com")

  every 10 seconds :
  <<
    # ...
  >>
 
  every 10 seconds :
  <<
    # ...
  >>
 

-A number of cleanup functions are available in the library; see below.
+A number of post functions are available in the library; see below.

 
 

-You can also write your own cleanup functions (in OCaml).  The
+You can also write your own post functions (in OCaml).  The

 function is passed one argument which is a C<Whentools.result> struct,
 defined below.
 
 function is passed one argument which is a C<Whentools.result> struct,
 defined below.
 


@@ -593,7 +621,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.


@@ -607,15 +636,15 @@ do not need to add it.
 Here are some examples of using the mailto function:
 
  job "ex.1"
 Here are some examples of using the mailto function:
 
  job "ex.1"

- cleanup (Whentools.mailto "you@example.com")
+ post (Whentools.mailto "you@example.com")

  every 10 seconds :
  <<
    # do something
  >>
 
  job "ex.2"
  every 10 seconds :
  <<
    # do something
  >>
 
  job "ex.2"

- cleanup (Whentools.mailto ~only_on_failure:true
-                           "you@example.com")
+ post (Whentools.mailto ~only_on_failure:true
+                        "you@example.com")

  every 10 seconds :
  <<
    # do something
  every 10 seconds :
  <<
    # do something


@@ -625,7 +654,7 @@ Here are some examples of using the mailto function:
  let to_addr = "you@example.com"
  
  job "ex.3"
  let to_addr = "you@example.com"
  
  job "ex.3"

- cleanup (Whentools.mailto ~from to_addr)
+ post (Whentools.mailto ~from to_addr)

  every 10 seconds :
  <<
    # do something
  every 10 seconds :
  <<
    # do something


@@ -660,14 +689,16 @@ Set variable I<name> to the floating point value I<f>.
 
 =item B<Whentools.result>
 
 
 =item B<Whentools.result>
 

-This structure is passed to cleanup functions.  It has the following
+This structure is passed to post functions.  It has the following

 fields:
 
  type result = {
 fields:
 
  type result = {

-   res_job_name : string; # job name
-   res_code : int;        # return code from the shell script
-   res_tmpdir : string;   # temporary directory script ran in
-   res_output : string;   # filename of stdout/stderr output
+   res_job_name : string;  # job name
+   res_serial : big_int;   # job serial (same as $JOBSERIAL)
+   res_code : int;         # return code from the shell script
+   res_tmpdir : string;    # temporary directory script ran in
+   res_output : string;    # filename of stdout/stderr output
+   res_start_time : float; # when the job started

  }
 
 =back
  }
 
 =back