...
Sharing One Server Check-Out Among Several Commands
Sometimes it can be useful to acquire a remote server and run several commands in sequence on that server. This is called a shared server scenario. The mechanism for accomplishing this goal is to add a server check-out specification to the enclosing Task and then reference the task-id on each Cmd or RemoteCmd that needs the server slot.
For example:
Task {SharedServer example} -id {bob} -service {pixarRender} -cmds {
Cmd {rsh %h mkdir /tmp/somedir} -refersto {bob}
Cmd {rsh %h render -Progress some.rib} -refersto {bob}
} -cleanup {
# Clean-up commands go here.
# This example uses RemoteCmd just to illustrate its use as an
# alternative to rsh above. Note that there is an implicit '%h'
# used to determine where the command should be run.
#
RemoteCmd {/bin/rm -rf /tmp/somedir} -refersto bob
} -subtasks {
# the description of any nested dependent tasks go here
[...]
}
The lifetime of the check-out is governed by two factors. The initial task-level check-out is done lazily in the sense that it only occurs when one of the commands that references it actually becomes the next command to be executed. A reference count is used to determine when it is safe to check the slot back in, it is freed when the last command to reference it has completed or errored out.
Syntax Note: the characters allowed in the idref names are letters, numbers, period (.), and underbar(_). For all of the % substitutions above, braces may be used delimit names, as in csh or Tcl; for example, if the current schedule has a service of type "renderserver" defined for the host named "percival", then a Task containing this command:
RemoteCmd {renderer -use %{h}.settings} -service {renderserver}
might cause the following command to be launched:
renderer -use percival.settings
The braces are required in this case because the simpler string "%h.settings" would cause the substitution mechanism to look for a Task or Cmd with "-id h.settings" and use its current values.
| Anchor | ||||
|---|---|---|---|---|
|
Tractor makes two passes through the scripts submitted to it. The first, a spool-time parsing pass, is used to construct the "shape" of the job; it sets up the hierarchy of tasks. The second pass (and possibly subsequent identical passes) is the dispatching, run-time, pass during which commands are launched and run-time substitutions are made, etc.
The initial parsing of the cript is done using a system built around John Ousterhaut's TCL interpreter. As a result, the TCL syntax rules apply to command arguments and string formation. Scripts consist of calls to the Job, Task, Cmd, and Instance commands (operators), which in turn take strings as arguments. In the case of Task, the -subtasks option can contain additional scripts, which are parsed recursively. In general, the TCL rules, as they apply to operator arguments, are much simpler than those for the Bourne shell (sh) or csh(1). Shell programmers should be aware of several things:
- launch expressions are tokenized and passed directly to execvp(2); hence semi-colon separated command sequences, command pipelines, environment variable references, and filename meta-characters (e.g. *,?,[]) are not directly supported (instead use an appropriate sub-shell).
- Tractor (and Alfred) will do tilde-expansion, as in csh
- single-quotes have no special meaning (i.e. they don't group words together), use braces - {} - for grouping.
- only one tokenizing pass is made through each argument string.
For example, consider using find(1) to remove files that start with "preview" from a directory tree. In a csh(1) script the command might look this way:<
find ~bob -type f -name 'preview.*' -exec /bin/rm {} \;
that is, the asterisk must be escaped from the shell filename expansion because it is used directly by the find command; similarly with the semicolon after the exec expression. The curly braces are untouched by the shell (since they're not part of a variable expression). If a similar command was part of a Tractor/Alfred script (as a Task's clean-up command for example), it would look like this:
Cmd {find ~bob -type f -name preview.* -exec /bin/rm \{\} ;}
Shell Pipelines and other Expressions
Given the restrictions just described above on Cmd launch expressions there are nonetheless occasions when shell constructs, such as command pipelines or run-time filename expansion, can be very useful. In these situations, a simple solution is to launch an appropriate shell as the Cmd, passing the pipeline expression to the shell via command-line arguments:
Cmd {/bin/sh -e "cd /tmp/frames; ls -1 | xargs -I+ cp + /DDR"}
Script authors should read the documentation for their shell of choice to understand the implications of various invocation options. For example, you must decide whether the user's .cshrc or .profile should be executed when the dispatcher launches a command like the above.
Another approach is to use the Cmd -msg option to pass arbitrary expressions to a launched shell. This is essentially equivalent to the above approach, but not as compact; however, it does allow for persistent reuse of the shell, if that's desired. Consider the following examples which send mail, which can sometimes be handy at the end of job. Recall that the -s option to Mail looks for the next "word" as the subject, so spaces need to be escaped (using csh(1) syntax this time):
Cmd {/bin/csh -fc "/usr/sbin/Mail -s 'job done' jean < ~/errlog"}
Cmd {/bin/csh -fet} -msg {/usr/sbin/Mail -s 'job done' jean < ~/errlog}
Often the simplest solution for complex expressions is to write a short shell script in your favorite language and launch the script from Tractor:
Cmd {myscript}
If a remote server is required, the run-time host selection can be passed to the script as an argument:
Cmd {myscript %h} -service {someServerType}
...