X-Git-Url: http://git.annexia.org/?p=whenjobs.git;a=blobdiff_plain;f=tools%2Fwhenjobs.pod;h=8455bcf5726f12525cb9b03582a7b9e8d60a3c95;hp=466bdb1bbd87b4d64cf12e2f572115862b041b49;hb=9f7c94086330deb1c6dc0c51355a60b19ff78055;hpb=03b83c1a4bab53d8914c6946ad892bca30df09d0 diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod index 466bdb1..8455bcf 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: @@ -43,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,12 +79,41 @@ Variables are stored (per-user) in the daemon. You can use the 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 @@ -127,6 +156,17 @@ C is used. 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. @@ -150,7 +190,7 @@ source, eg: whenjobs --lib $builddir/lib -e -=item B<--set> variable value +=item B<--set> variable=value [variable=value ...] =item B<--type> bool|int|float|string|unit @@ -158,18 +198,35 @@ 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. @@ -182,13 +239,26 @@ may cause unexpected results, so use with caution. 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. +Compile the jobs file(s) and upload it to the daemon, without editing. Note that the I<--edit> option does this automatically. Furthermore, when the daemon is started it checks for a jobs script and loads it if found. +See also L below. + =item B<--variables> Display all the variables and their values, in the format C. @@ -199,11 +269,24 @@ Display all the variables and their values, in the format C. Display the name and version of the program and exit. -=item B<-help> +=item B<--whisper> variable=value [variable=value ...] -=item B<--help> +This works the same way as the I<--set> option, but with the +difference that jobs' when clauses are not reevaluated. In other +words, the variables are set, but "quietly" so as not to trigger any +jobs to run. -Display brief usage and exit. +Note that this can lead to some unexpected results: one case is a +job such as: + + when changed a || changed b : << ... >> + +If C is changed using I<--whisper>, then the job will not run. + +But later on, if C is set but to the same value that it already has +(ie. not changed), the job will run because the whole when-clause is +reevaluated and C is found to have changed since the last run of +the job. =back @@ -323,7 +406,7 @@ A when statement has the form: >> where CexprE> is a I, described below. -Don't forget the colon character between the period expression and the +Don't forget the colon character between the expression and the shell script. A when statement is a job which runs when the conditions described in @@ -364,6 +447,12 @@ If the sub-expressions are numeric, then numeric comparison is done. If either sub-expression is non-numeric, then both expressions are converted (if necessary) to strings and string comparison is done. +=item I BE> I + +=item I B I + +Either form can be used to test the two expressions for inequality. + =item B I Boolean negative of I. @@ -419,7 +508,7 @@ uploaded, try giving the jobs an explicit name. If the named variable has changed since this job last ran, then this evaluates to true, else false. -This is the same as writing C. +This is the same as writing C. =item B I @@ -779,6 +868,53 @@ fields: =back +=head1 MULTIPLE JOBS FILES + +The whenjobs I<-e> and I<-l> options edit and list a file called +C<$HOME/.whenjobs/jobs.ml>. + +You can also edit C<$HOME/.whenjobs/jobs.ml> by other means (eg. your +own editor). After editing, to recompile and upload it, use: + + whenjobs --upload + +When you have lots of jobs, it is convenient to split the jobs across +multiple files. Any C<*.ml> files located in C<$HOME/.whenjobs> can +be used (with some restrictions on filenames -- see below). These are +compiled and loaded into the daemon using the I<--upload> command. + +To create multiple jobs files, you cannot use the I<-e> or I<-l> +options. Instead you have to create them yourself in +C<$HOME/.whenjobs>, and when you have finished creating or editing +them, upload them. + +=head2 FILENAME RESTRICTIONS ON JOBS FILES + +In OCaml, a file called C corresponds to an OCaml module +called C (note the capitalization). OCaml module names can only +contain ASCII alphanumeric characters, underscore, and C<'> (single +quote), and they must begin with an alphabetic character. The same +rules apply to jobs files. + +Furthermore, various OCaml module names are reserved (eg. C, +C). It is therefore better to prefix any names with something +specific to your application. + +Examples of legal filenames are: + + foo.ml + app_foo.ml + app_123.ml + jobs.ml + +Examples of illegal filenames are: + + ann.txt # must end with .ml + 123.ml # must begin with alphabetic + app!.ml # must contain alphanumeric or underscore + app-foo.ml # must contain alphanumeric or underscore + map.ml # reserved module name + =head1 FILES