Job is a set/list of tasks (it is generally a set, but order of tasks have some meaning). These tasks may have dependencies (arbitrary number), which needs to be observed. When recodex-worker processes job, it creates a task graph, where tasks are vertices and dependencies are edges (A -> B means that the task A is on the dependency list of task B) and creates its linear ordering. The graph must be acyclic (otherwise linear ordering will not exist) and the recodex-worker attempts to execute maximal number of tasks possible. Tasks without dependencies can be executed directly, other tasks are executed when all their dependencies have been successfully completed.
Tasks are executed sequentially -- by the linear ordering of the task graph. Parallel tasks (tasks, which are not directly dependent and thus their linear ordering may be arbitrary) are ordered first by their priority (higher number => higher priority) and second by their order in the configuration file. Priority is important for specifying evaluation flow. See sample picture for better understanding.
Each task has a unique ID (alphanum string like _CompileA_, _RunAA_, or _JudgeAB_ in the picture). These IDs are used to identify tasks (for dependency references, in the log, ...). Numbers in bottom right corner are priorities of each task. Higher number is greater priority. It means, that if task _RunAA_ is done, next must be _JudgeAA_ and not _RunAB_ (that will be also valid linear ordering, but _RunAB_ has lower priority).
- **Execute external process** (optionally inside Isolate). Linux default will be mandatory in Isolate, this option is here because of Windows.
- **Perform internal operation**. External processes are meant for compilation, testing, or execution of external judges. Internal operations comprise commands, which are typically related to file/directory maintenance and other evaluation management stuff. Few important examples:
Even though the internal operations may be handled by external executables (`mv`, `tar`, `pkzip`, `wget`, ...), it might be better to keep them inside the recodex-worker as it would simplify these operations and their portability among platforms. Furthermore, it is quite easy to implement them using common libraries (e.g., _zlib_, _curl_).
These tasks are typically executed in isolate (with given parameters) and the recodex-worker waits until they finish. The exit code determines, whether the task succeeded (0) or failed (anything else). A task may be marked as essential; in such case, failure will immediately cause termination of the whole job.
- **stdout** and **stderr** - can be individually redirected to a file or discarded. If this output options are specified, than it is possible to upload output files with results by copying them in result directory.
- **limits** - task have time and memory limits; if these limits are exceeded, the task also fails.
The task results (exit code, time, and memory consumption, etc.) are saved into result yaml file and eventually sent back to frontend application to address which was specified on input.
For each job execution unique directory structure is created. Job is not restricted to specified directories (tasks can do whatever is allowed on system), but it is advised to use them inside job. In recodex-worker configuration one can specify worker default directory, this is base of every file which is produced by recodex-worker.
- **${DEFAULT}/results/${WORKER_ID}/${JOB_ID}** - again accessible directory from job configuration which is used to store all files which will be upload on fileserver, usually there will be only yaml result file and optionally log, every other file has to be copied here explicitly from job
Configuration of the job which is passed to worker is generated from two parts:
- **template** - Common template for similar kinds of tasks. Contains allmost all instructions - when fetch, move, rename files, run commands, judges, ..., task dependencies and priorities. This template can be shared by more problem assignments or every problem (probably in compiller class) can have different one.
This configuration example is written in YAML and serves only for demostration purposes. Therefore it is not working example which can be used in real traffic. Some items can be omitted and defaults will be used.
Because frontend does not know which worker gets the job, its necessary to be a little general in configuration file. This means that some worker specific things has to be transparent. Good example of this is directories, which can be placed whenever worker wants. In case of this variables were established. There are of course some restrictions where variables can be used. Basically whenever filesystem paths can be used, variables can be used.
Usage of variables in configuration is then simple and kind of shell-like. Name of variable is put inside braces which are preceded with dollar sign. Real usage is than something like this: ${VAR}. There should be no quotes or apostrophies around variable name, just simple text in braces. Parsing is simple and whenever there is dollar sign with braces job execution unit automatically assumes that this is a variable, so there is no chance to have this kind of substring.
- **EVAL_DIR** - evaluation directory which should point inside sandbox. Note, that some existing directory must be bound inside sanbox under **EVAL_DIR** name using _bound-directories_ directive inside limits section.
- **RESULT_DIR** - results from job can be copied here, but only with internal task
- **TEMP_DIR** - general temp directory which is not dependent on operating system
- **JUDGES_DIR** - directory in which judges are stored (outside sandbox)
## Results
Results of tasks are sent back in YAML format compressed into archive. This archive can contain further files, such as job logging information and files which were explicitly copied into results directory.
Results file contains job identification and results of individual tasks.
### Results items
Mandatory items are bold, optional italic.
- **job-id** - identification of job to which this results belongs
- **results** - list of tasks results
- **task-id** - unique identification of task in scope of this job
- **status** - two states: OK, FAILED
- _error_message_ - defined only in internal tasks on failure
- _sandbox_results_ - if defined than this task was external and was run in sandbox
- **exitcode** - integer which executed program gave on exit
- **time** - time in seconds in which program exited
- **wall-time** - wall time in seconds
- **memory** - how much memory program used in kilobytes
- **max-rss** - maximum resident set size used in kilobytes
- **status** - two letter status code: OK, RE, SG, TO, XX
- **exitsig** - description of exit signal
- **killed** - boolean determining if program exited correctly or was killed
During execution tasks can use only one shared log. There is no use for multiple logs which will be used in all tasks, because of pretty small amount of information which is loged. Log is in default disabled and can be enabled in job configuration, then all logged actions in tasks will be visible here.
