You are here: References > Task File

3.2 Task File

A task file contains a list of Nitro task definitions (task execution options) along with the task command line Nitro will execute. Since the Nitro coordinator will be running on one of the nodes allocated to the Nitro job, the task file must be accessible to the node on which the coordinator will run.

The task file is a text file where each task definition must be contained on a single line. Lines of text may be terminated by either a Linux-style line ending (LF or '\n' new line character) or a Windows-style line ending (CR/LF - '\r\n' carriage return/line feed combination). The line number is reported in the task log so that errors in the task file can be quickly located and fixed.

The task file allows comment and empty lines. A hash symbol (#) in the first column of a line identifies a comment line.

Each task will be assigned a task ID, which will start at 1 and increment with each task line (comment and empty lines are not assigned a task ID). This task ID is passed to the task in the NITROTASKID environment variable.

3.2.1 Task Options

Task options are name/value pairs that are listed before the task's command line of the form "<option>=<value>". Task options must be specified before the task's command line to be executed. As Nitro parses the line, it will stop looking for name/value pairs as soon as it finds a character string that does not include the name/value delimiter (=) or is the "cmd" option. Everything after the "cmd=" option or the first string that is not delimited as a name/value pair will be considered part of the task command line.

Task definitions that contain errors (such as a misspelled option) are considered "invalid" tasks and will be reported in the task log along with an explanation of the error in the line. Examples of valid command lines are as follows:

# Commented line
/opt/framemaker/bin/assemble_frame --input /shared/scene23.def --time-index 0
cmd=/opt/framemaker/bin/assemble_frame --input /shared/scene23.def --time-index 0

name=Scene23Time0 /opt/framemaker/bin/assemble_frame --input /shared/scene23.def --time-index 0
name=Scene23Time0 maxtime=30 cmd=/opt/framemaker/bin/assemble_frame --input /shared/scene23.def --time-index 0

The following describes the various task options.

Application Command – The coordinator considers everything immediately after the equal sign (= in "cmd=") as the task's "application" command line, which a worker will execute. There must be at least one non-whitespace character immediately after the "=" or the coordinator declares the task definition invalid. The application command line permits standard I/O redirection and environment variable substitution.

cmd=<xxx -y zzz>

Do not place any task options after the command line or the coordinator will not parse them; assumes they are part of the command line.
Labels – Specifies the labels assigned to a task.

This is optional and there is no default value.

If given, a label must be composed of letters, digits, underscore, hyphen, and/or period. Use a comma to separate multiple labels.

If the option's value violates the conditions above, the coordinator will declare the task definition invalid and will not send the task to a worker.

When the coordinator logs the task in the Completed Tasks Log file, it outputs this option's value "as is", meaning without alternation and with no substitution of commas with spaces.

labels=<list>
Maximum Time – Maximum time (in seconds) a task may execute after which the worker will terminate it. This is optional; the default value is 3,600 seconds (1 hour).

If given, the value must be less than the maxtime-limit <period> value.

If the option's value is non-numeric, non-decimal, or outside the allowed range, the coordinator will declare the task definition invalid and will not send the task to a worker.

maxtime=<nn>
Name – Unique name assigned to your task definition. Task names do not have to be unique, but creating a unique task name will help to identify tasks.

name=<task name>
Task Cores – Number of OS cores that the task requires. Nitro will allocate the number of cores requested and set the affinity of the task to the available cores.
```
cores=<count>
```
The command line options "‑‑thread‑count" or "‑‑thread‑ratio" affect the number of available cores. If you use either of these options and they specify more cores than the node has available, Nitro will not pin the task to a specific core. If a task is specified to require more cores than the node that receives the task assignment, the task will not run.

Users should submit their jobs so that tasks can run on any of the nodes that are allocated to the job. If, for example, you have some tasks that require 20 processors, but there are some 16 core nodes in the cluster, the job should be submitted so that it only allows 20 proc nodes to be allocated to the job. If a Nitro worker is assigned a job with requirements that it cannot fulfill (either too many cores, or too much memory) the task will be counted as failed, and Nitro will show the status of "InsufRes" for that task in the task log file.
Task Environment Variables – Specifies a list of user supplied environment variables that will be set in the context of the task. The list of environment variables can be one or more name/value pairs separated by commas. Environment variable name value pairs cannot contain spaces.
```
env=<name=value>[,<name=value>,...]
```
Task Memory – Maximum amount of memory that the task requires. Nitro determines the amount of physical memory available on the system and uses this number as the limit that can be allocated by concurrent tasks. If no units are specified, GB is assumed. Available unit specifications include "GB" (10^9 bytes), "GiB" (2^30 bytes), "MB" (10^6 bytes), and "MiB" (2^20 bytes). Nitro uses MB units in debug logs.
```
memory=<amount>
```
Users should submit their jobs so that tasks can run on any of the nodes that are allocated to the job. If, for example, you have some tasks that require 32 GB, but there are some 16 GB nodes in the cluster, the job should be submitted so that it only allows 32 GB nodes to be allocated to the job. If a Nitro worker is assigned a job with requirements that it cannot fulfill (either too many cores, or too much memory) the task will be counted as failed, and Nitro will show the status of "InsufRes" for that task in the task log file.
Task Shell – Specifies the task shell, if any, to use. Tasks are normally executed by running "/bin/bash -c <task command line>".
```
shell=[default | none | <shell path>]
```
- The default shell provides translation of environment variables into command line options and other command line processing benefits.
- In high-throughput environments performance gains can be realized by using a lighter weight shell such as the Bourne shell or Korn shell.
- If no command line processing is needed, the task can be run without a shell.
- Executing a task directly instead of using the shell can speed task invocation by more than 50% over the default shell.
When specifying a shell other than the default shell, the fully qualified path should be used. For example, if you want to use the Bourne shell you should specify the shell as "/bin/sh" as opposed to just "sh".