X-Git-Url: https://git.arvados.org/arvados.git/blobdiff_plain/b54a5ea817d3d2087eaa07dcf98ec8a82af56d06..4f4f0f57721d854aaddec8ab7dbc8759075717b5:/doc/api/methods/jobs.html.textile.liquid?ds=sidebyside diff --git a/doc/api/methods/jobs.html.textile.liquid b/doc/api/methods/jobs.html.textile.liquid index f3e51fcbd2..351a77792f 100644 --- a/doc/api/methods/jobs.html.textile.liquid +++ b/doc/api/methods/jobs.html.textile.liquid @@ -6,7 +6,7 @@ title: "jobs" ... -h1. jobs + Required arguments are displayed in %{background:#ccffcc}green%. @@ -21,7 +21,7 @@ table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | {background:#ccffcc}.|uuid|string||path|| -h2. create +h2(#create). create Create a new Job. @@ -29,7 +29,97 @@ Arguments: table(table table-bordered table-condensed). |_. Argument |_. Type |_. Description |_. Location |_. Example | -|job|object||query|| +{background:#ccffcc}.|job|object||query|| + +Attributes of 'job' parameter: + +table(table table-bordered table-condensed). +|_. Attribute |_. Type|_. Accepted values |_. Description| +{background:#ccffcc}.|script |string |filename |The actual script that will be run by crunch. Must be the name of an executable file in the crunch_scripts/ directory at the git revision specified by script_version.| +{background:#ccffcc}.|script_version |string |git branch, tag, or commit hash |The version of code to run, which must be available in the specified repository.| +{background:#ccffcc}.|repository |string |name of git repository hosted by Arvados |The repository to search for script_version.| +{background:#ccffcc}.|script_parameters |object |any JSON object |The input parameters for the job, with the parameter names as keys mapping to parameter values.| +|minimum_script_version |string |git branch, tag, or commit hash |The minimum acceptable script version (earliest ancestor) to consider when deciding whether to re-use a past job.| +|exclude_script_versions|array of strings|git branch, tag, or commit hash|Script versions to exclude when deciding whether to re-use a past job.| +|nondeterministic |boolean | |If true, never re-use a past job, and flag this job so it will never be considered for re-use.| +|no_reuse |boolean | |If true, do not re-use a past job, but this job may be re-used.| + +When a job is executed, the 'script_version' field is resolved to an exact git revision and the git hash for that revision is recorded in 'script_version'. If 'script_version' can't be resolved, the job submission will be rejected. + +h3. Reusing jobs + +Because Arvados records the exact version of the script, input parameters, and runtime environment [1] that was used to run the job, if the script is deterministic (meaning that the same code version is guaranteed to produce the same outputs from the same inputs) then it is possible to re-use the results of past jobs, and avoid re-running the computation to save time. Arvados uses the following algorithm to determine if a past job can be re-used: + +notextile.
+{ + "script": "hash.py", + "repository": "you", + "script_version": "master", + "script_parameters": { + "input": "c1bad4b39ca5a924e481008009d94e32+210" + } +} +
+{ + "script": "hash.py", + "repository": "you", + "script_version": "d00220fb38d4b85ca8fc28a8151702a2b9d1dec5", + "script_parameters": { + "input": "c1bad4b39ca5a924e481008009d94e32+210" + } +} +
+{ + "script": "hash.py", + "repository": "you", + "minimum_script_version": "earlier_version_tag", + "script_version": "master", + "exclude_script_versions": ["blacklisted_version_tag"], + "script_parameters": { + "input": "c1bad4b39ca5a924e481008009d94e32+210" + } +} +
+{ + "script": "monte-carlo.py", + "repository": "you", + "script_version": "master", + "nondeterministic": true, + "script_parameters": { + "input": "c1bad4b39ca5a924e481008009d94e32+210" + } +} +