Contents
Synopsis
Tractor and Alfred share a common scripting language. Input scripts for both are composed of expressions using the following operators:
Job [options]
Task {title} [options]
RemoteCmd {launch_expr} [options]
Cmd {launch_expr} [options]
Instance {task_title_to_reference}
Iterate varname -from n -to m -by i -template {script} [options]
See the Scripting document for the general concepts and examples.
Operator Details
The options listed below have the form "-optionName optionValue" and all options must be on the same logical input line as the operator. Backslash (\) can be used at the end of a line to explicitly escape the newline and continue input on the next line of the script file. Newlines within (curly) braces are treated as blanks and can improve clarity, especially for nested tree structures.
For example:
Task {frame.1} -subtasks {} -cmds {Cmd {/bin/date} -tags {simple}}
can also be written as:
Task {frame.1} -subtasks { } -cmds { Cmd {/bin/date} -tags {simple} }
Job [options]
-title {job title text}
-after {date}
-afterjids {jobid jobid ...}
-subtasks {Tasks or Instances}
-cleanup {Cmd list}
-atleast min_slots
-atmost max_slots
-maxactive max_commands
-tags {tag tag ...}
-projects {name name ...}
-tier {name}
-service {key expression}
-envkey {key} -envkey {{key1} {key2} {key3}}
-priority float
-crews {crew name(s)}
-avoid {service names...}
-etalevel n
-comment {text}
-metadata {text}
-editpolicy {policy_name}
-dirmaps {{{srcdir} {dstdir} zone} ...}
-postscript {cmd_list} -whendone {shell_command} -whenerror {shell_command}
The optional "-postscript" clause can be added to the main "Job" keyword in a job script. This clause adds Cmds or RemoteCmds that will be executed after those in the main job proper, in the following situations: (1) after the main job tasks have all completed successfully; and (2) after the main job stalled due to errors, when all other remaining tasks are blocked by errors in subtasks. These commands are similar in spirit to constructs like the "finally" block in a Python exception handler. This clause is structured just like the "-cmds" block in task:
Job -title {...} -subtasks { Task {...} -cmds { } } -postscript { Cmd {touch /tmp/always_runs_on_spooling_host} -when always RemoteCmd {touch /tmp/there_were_errors} -when error RemoteCmd {touch /tmp/all_done_with_no_errors} -when done }
The old alfred scripting constructs "-whendone' and "-whenerror" are implemented in Tractor as special cases of the -postscript clause. For compatibility reasons they are translated to local Cmds (requiring a tractor-blade on the user's spooling host), unless the tractor-spool option "--remotecleankeys=kkkk" is given. These commands launch the given "when" command via a "system shell" in order to accommodate shell expressions allowed by the old syntax. The newer postscript syntax, with "RemoteCmd {...} -when {...}" is recommended instead.
Task {title} [options]
title
-subtasks {Tasks or Instances}
-cmds {Cmd list}
-cleanup {Cmd list}
-chaser {launch_expr}
-preview {launch_expr}
-service {server keys}
-serialsubtasks 1
-id {name}
-resumeblock 1
This option works together with the RemoteCmd option -resumewhile (below) to implement a simple form of incremental checkpoint-resume cycle within a job. A Task with this option marks the "top" of a looping scope, namely the task-tree hierachy represented by this task's -subtask dependencies (and their dependencies).
If any RemoteCmd below this Task encounters a True "resumewhile" condition when its command exits, then all Tasks along the path from the RemoteCmd to this "resumeblock" Task will be automatically relaunched repeatedly until all "while" conditions are False.
The goal of this scheme is to allow a series of related commands to execute to a sensible checkpoint condition, likely leaving a reviewable intermediate result. Then the entire chain of tasks is executed again, applying additional incremental work to the intermediate result.
RemoteCmd specifies the name of a command-line program that Tractor will launch on some tractor-blade host on the compute farm. The "-service" expression specifies the host types that are appropriate to run the given command. Other options include environment configuration keys, and tracking controls for scarce resources. For example:
RemoteCmd {prman /shared/rib/some.rib} -service PixarRender
The prman executable will be launched on a Tractor blade server that provides the PixarRender service. In simple terms that means that a command will be dispatched when its service keyword matches an available blade.
These keys can be chosen arbitrarily by site administrators to represent, abstractly, capabilities of different types of hosts; they might represent installed software, or operating systems, or CPU architecture or graphics hardware. Each category of tractor blade profile lists different combinations of these keywords. Each job, or individual command in a job, then lists the keys that must be present on a host for it to run correctly. By convention, the "PixarRender" keyword is used to describe hosts where the Pixar RenderMan software is installed.
Parameter details:
appname
the name of an application to launch, and its arguments. See the launch expression discussion for details on runtime substitution variables and restrictions (especially with regard to shell-style command pipelines). This must be a properly tokenized and escaped Tcl list; a blank-delimeted list is sufficient for simple commands, but in general use nested curly-braces to clearly distinguish tokens that may contain spaces, etc. For example:
RemoteCmd {/bin/ps -eaf} -service Linux RemoteCmd {{C:\\app path\\appname} {arg1} {arg two}} -service Windows
See the parameter substitution list for run-time values that tractor-blade will add before launching the command. For commands that are participating in a resume block cycle, the substitution pattern "%r" is particularly useful since it will be "1" when a computation is resumed from a checkpoint. Similarly the pattern "%R" will be an incrementing integer giving the current continuation pass count, starting with 0. The pattern %q will have the value 1.0 when a task is being executed due to final quality runs from the subtasks it depends upon, it will be less than 1.0 if some subtask only reached a checkpoint during this resumewhile loop.
-service {server keys}
-tags {limit tag list}
-maxrunsecs {float_maximum_allowed_runtime} -minrunsecs {float_minimum_acceptable_runtime}
Task Elapsed Time Bounds -- specifies an acceptable elapsed time range, in seconds, for a given launched command. Commands with elapsed times outside the acceptable range will be marked as an error. Commands that run past the maximum time boundary will be killed. Both parameters are optional. The default value for minrunsecs is 0.0, and the default for maxrunsecs is unlimited. Example job script syntax:
RemoteCmd {sleep 15} -service PixarRender -minrunsecs 5 -maxrunsecs 20
-atleast min_slots
-atmost max_slots
-envkey {key} -envkey {{key1} {key2} {key3}}
specifies an arbitrary key or keys (a name or list of names or other strings) that will be passed to tractor-blade. If this option is not specified, then the command inherits the settings given at the Job level. Based on each envkey string, and other properties such as user name, tractor-blade will invoke a series of environment handlers that prepare environment variables such as paths and other settings prior to launching each command. There are several built-in key handlers, and custom handlers can also be added. The handlers available for each type of blade are specified with the "EnvHandler" settings in blade.config. One usage scenario addresses the common requirement for a given production to lock down a variety of paths and other pipeline env settings. These settings can be neatly encapsulated in a single handler definition, and then each job simply specifies -envkey=NAME to have the given collection of settings applied to its commands. Since a single tractor-blade may launch commands from many different jobs, sometimes concurrently, and each job may require unique env settings for its show, the blade applies the env handler set-up as part of each command's launch procedure.
A special key of setenv can be used to set specific environment variables. For example, {setenv SRC=/src/path DST=/dst/path} could be used in concert with a command like cp $SRC $DST.
A command-level envkey setting causes the job-level envkey setting to be ignored.
-id {name}
-refersto idref
-expand 1/0
setting the option value to 1 indicates that this command produces new Tractor task descriptions as its output. This is a mechanism for growing the job task hierarchy dynamically during the execution of the job. Everything printed to stdout by the launched app will be collected when the command completes, and will be assumed to be syntactically valid Task descriptions. Those new tasks will become new subtasks of the current Task. This feature has primarily used by processing pipelines that prefer a just-in-time style of processing where commands procedurally generate assets based on prior results, rather than "unrolling" all processing steps at job authoring time.
Tractor 1.7 also supports setting the value to a filename (string). In this case the running application is expected to coded or parameterized to write the task descriptions into the named file, rather than writing them to stdout. Then tractor-blade will send the file contents to the engine for insertion into the parent job. After delivering the contents, tractor-blade will remove the file. Note that since several such commands may be running simultaneously on a given blade, it is important to chose unique names for the temporary expand file.
Tractor 2.1 also introduced an expand variant intended for use by long-running applications that generate a series of results, such as simulations. In this situation, the application might want to inject new tasks that can run in parallel with the ongoing application itself -- unlike the other expand use cases where the expand text is sent after the application has fully exited. To use this concurrent approach, the application should write the new task descriptions to a temporary file; then it should emit a line of the form:
TR_EXPAND_CHUNK "filename"
to stdout. Note the important required double-quotes around the filename. Tractor-blade will detect that line and then deliver the contents of that file to the engine. Once the delivery occurs, then tractor-blade will remove the temporary file.
-msg {text_for_app_stdin}
-retryrc {integer_return_codes}
-resumewhile {condition}
This option is part of mechanism for implementing a simple checkpoint-resume form of incremental processing. It is only meaningful when combined with the Task option "-resumeblock" and with an application that is compliant with this continuation model.
When this option is given, then the command being launched is expected to exit after performing an incremental amount of work. This option requests that Tractor should relaunch the same command repeatedly until the command determines that it has finally completed its overall work. Stated another way: the command will consume a fixed amount of CPU time and then yield the blade to another command with the expectation that Tractor will eventually relaunch it so that it can resume processing. This simple continuation mechanism requires several cooperating components:
The condition expression is used by tractor-blade to determine whether the command process exit represents an intermediate checkpoint, or the final completion of the particular task. There are two supported expressions:
- {exitcode NNN} -- the keyword "exitcode" causes tractor-blade to examine the process exit status code. If the numeric code matches the given value, then a checkpoint has been reached, and the command will be relaunched later. This condition can be read as "resume this command while the exitcode is NNN", otherwise the command should be considered finally complete if the exit code is zero, or to have encountered an error for any other value.
- {testcheckpoint TYPE VALUE} -- the keyword testcheckpoint causes tractor-blade to perform one of several built-in tests for command completion. Today, the only supported TYPE is the keyword "exr" referring to the OpenEXR image format, and a VALUE which is an output image filename. Tractor-blade will examine the named image to see if it contains auxilliary data indicating that it is an incomplete checkpoint image. If the image is a checkpoint, then Tractor will schedule another incremental execution of the command. If the image is not a checkpoint image then the rendering is considered to be complete, or an error depending on the process exit status.
-resumepin 1
Cmd {appname [app args]} [options]
This operator, also referred to as "local Cmd" is only used in a few restricted cases, and it accepts the same options as RemoteCmd, above. There are two important differences:
- The specified application is constrained to execute on the same user desktop host that spooled the job. This may be valuable in the case where the command presents a UI or displays an image, or if it must access files that are only on that machine. Therefore, the user's desktop machine must also be running a tractor-blade so that tractor-engine can dispatch the command back to it.
- In the case of netrender (or rare applications like it), Tractor can collect several available remote blades to be used in concert with the user's desktop local blade. See the "-atleast" description below.
-atleast {min_servers} -atmost {max_servers}
-samehost 1
taskref
Assign varname {value_string}
NOTE: the Assign operator is deprecated and will not function in Tractor as it did in Alfred. Specifically the stored values will not be available in future "expand" tasks, and the job parsing and substitution modes can effect whether substitions occur at all. Variable substituion of this type is usually better suited to the scripting environment that is creating the job script, such as the Tractor job authoring API for Python.
varname
varname
-from nnn
-to nnn
-by nnn
-subtasks {Tasks or Instances}
-template {Tasks or Instances}