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:
whenjobs --jobs
whenjobs --cancel serial
whenjobs --start "name"
+ whenjobs --tail serial
=head1 DESCRIPTION
<<
# 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
command line tool to examine and set variables:
$ whenjobs --variables
- load=0.9
- $ whenjobs --set cat sushi
+ JOBSERIAL=297
+ libguestfs_build_local=1.17.16
+ libguestfs_commit=7e32d892d76a31f55e2a4151902623b9949e3efa
+ libguestfs_dist=1.17.16
+ libguestfs_release=1.17.16
+ libguestfs_stable_build_local=1.16.10
+ libguestfs_stable_commit=27433a0a335301441b1eb6244ba425c2c44b2d99
+ libguestfs_stable_dist=1.16.10
+ libguestfs_stable_release=1.16.10
+ libguestfs_stable_version=1.16.10
+ libguestfs_version=1.17.16
+ $ whenjobs --set cat=sushi
$ whenjobs --get cat
sushi
-The act of setting a variable (using I<--set>) can trigger jobs to run.
+Note: The act of setting a variable (using I<--set>) can trigger jobs
+to run.
+
+You can also list out what jobs are running:
+
+ $ whenjobs --jobs
+ 287 libguestfs-stable: fedora 16
+ running in: /tmp/whenjobsa2afc44fd757465f95438309f1a51609
+ started at: 2012-03-13 10:59:37
+
+and you can 'tail' the output of running jobs which is useful for
+debugging:
+
+ $ whenjobs --tail 287
+ Uploading: 147496271972717053d46b82a07435ca libguestfs-1.16.10.tar.gz
+
+You can start and cancel jobs manually:
+
+ $ whenjobs --start 'libguestfs: poll'
+ $ whenjobs --cancel 287
=head1 OPTIONS
Print the value of a variable.
+=item B<-help>
+
+=item B<--help>
+
+Display brief usage and exit.
+
+=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.
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
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<before> 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</REFERENCE> 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<cat> and C<food> are strings, and C<weight> 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<would> run, I<if> 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.
Display the name and version of the program and exit.
-=item B<-help>
-
-=item B<--help>
-
-Display brief usage and exit.
-
=back
=head1 REFERENCE
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
git.annexia.org / whenjobs.git / blobdiff