Add commands to list, cancel, start jobs.

[whenjobs.git] / tools / whenjobs.pod

diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod
index 1c96648..2958eba 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
 
+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
@@ -83,6 +89,14 @@ The act of setting a variable (using I<--set>) can trigger jobs to run.
 
 =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>
@@ -112,6 +126,13 @@ C<vi> is used.
 
 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>
@@ -128,6 +149,13 @@ 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
@@ -664,11 +692,12 @@ This structure is passed to cleanup functions.  It has the following
 fields:
 
  type result = {
-   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_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