A client may cancel a committed request early (before the assigned container finishes) by setting the request priority to zero.
-!{max-width:40em;max-height:70em}{{site.baseurl}}/api/methods/container_request_lifecycle.svg!
+!{max-width:60em;}{{site.baseurl}}/api/methods/container_request_lifecycle.svg!
{% comment %}
-# svg generated using https://dreampuf.github.io/
+# svg generated using `graphviz -Tsvg -O`
digraph {
- graph [nojustify=true] [labeljust=l];
+ graph [nojustify=true] [labeljust=l]
- invisiblestart [label = ""] [color=white];
+ invisiblestart [label = ""] [color=white] [group=lifecycle];
node [color=black] [fillcolor=white] [style=filled] [shape=box] [nojustify=true];
- uncommitted [label = "container request:\l state=Uncommitted\l"] [fillcolor=lightgrey];
- committed [label = "container request:\l state=Committed\l priority>0\l"];
- invisiblestart -> uncommitted [label = "user creates container request"];
- uncommitted -> committed [label = "user assigns state=Committed, priority>0\l"];
- queued [label = "container request:\l state=Committed\l priority>0\lcontainer:\l state=Queued\l"];
- committed -> queued [label = "Arvados creates\la new container\l"];
- locked [label = "container request:\l state=Committed\l priority>0\lcontainer:\l state=Locked\l"];
- queued -> locked [label = "Arvados is ready\lto dispatch the container\l"];
- running [label = "container request:\l state=Committed\l priority>0\lcontainer:\l state=Running\l"];
- locked -> running [label = "Arvados starts the\lcontainer process\l"];
-
- node [color=black] [fillcolor=lightblue] [style=filled] [shape=box];
- reused [label = "container request:\l state=Final\lcontainer:\l state=Complete\l(reused existing container)\l"];
- latecancelled [label = "container request:\l state=Final\lcontainer:\l state=Cancelled\l"];
- containerfinished [label = "container request:\l state=Final\lcontainer:\l state=Complete\l exit_code=0\l"];
- containerfailed [label = "container request:\l state=Final\lcontainer:\l state=Complete\l exit_code≠0\l"];
- reused -> latecancelled -> containerfailed -> containerfinished [style=invis];
-
- committed -> reused [label = "Arvados selects an\lexisting container\l"];
- queued -> latecancelled [label = "user assigns\lpriority=0"];
- locked -> latecancelled [label = "user assigns\lpriority=0"];
- running -> latecancelled [label = "user assigns\lpriority=0"];
- running -> containerfailed [label = "container process\lfails\l"];
- running -> containerfinished [label = "container process\lsucceeds\l"];
+ uncommitted [label = "container request:\l state=Uncommitted\l"] [fillcolor=lightgrey] [group=lifecycle];
+ {
+ rank=same;
+ committed [label = "container request:\l state=Committed\l priority>0\l"] [group=lifecycle];
+ reused [label = "container request:\l state=Final\lcontainer:\l state=Complete\l(reused existing container)\l"] [fillcolor=lightblue] [group=endstate];
+ }
+ invisiblestart -> uncommitted [label = " user creates container request\l"] [color=navy] [fontcolor=navy];
+ uncommitted -> committed [label = " user updates to\l state=Committed, priority>0\l"] [color=navy] [fontcolor=navy];
+ queued [label = "container request:\l state=Committed\l priority>0\lcontainer:\l state=Queued\l"] [group=lifecycle];
+ committed -> queued [label = " Arvados creates a new container\l"];
+ {
+ rank=same;
+ locked [label = "container request:\l state=Committed\l priority>0\lcontainer:\l state=Locked\l"] [group=lifecycle];
+ latecancelled [label = "container request:\l state=Final\lcontainer:\l state=Cancelled\l"] [fillcolor=lightblue] [group=endstate];
+ }
+ queued -> locked [label = " Arvados is ready to dispatch the container\l"];
+ {
+ rank=same;
+ running [label = "container request:\l state=Committed\l priority>0\lcontainer:\l state=Running\l"] [group=lifecycle];
+ containerfailed [label = "container request:\l state=Final\lcontainer:\l state=Complete\l exit_code≠0\l"] [fillcolor=lightblue] [group=endstate];
+ }
+ locked -> running [label = " Arvados starts the container process\l"];
+ containerfinished [label = "container request:\l state=Final\lcontainer:\l state=Complete\l exit_code=0\l"] [fillcolor=lightblue] [group=lifecycle];
+
+ committed -> reused [label = "Arvados selects an existing container"] [constraint=false] [labeldistance=0.5];
+ queued -> latecancelled [label = "user updates to priority=0"] [color=navy] [fontcolor=navy];
+ locked -> latecancelled [label = "user updates to priority=0"] [color=navy] [fontcolor=navy] [constraint=false];
+ running -> latecancelled [label = "user updates to priority=0"] [color=navy] [fontcolor=navy] [constraint=false];
+ running -> containerfailed [label = "container process fails"];
+ running -> containerfinished [label = " container process succeeds\l"];
+
+ # layout hacks
+ reused -> latecancelled [style=invis];
+ latecancelled -> containerfailed [style=invis];
}
{% endcomment %}
h2(#container_reuse). Container reuse
-When a container request is "Committed", the system will try to find and reuse an existing Container with the same command, cwd, environment, output_path, container_image, mounts, secret_mounts, runtime_constraints, runtime_user_uuid, and runtime_auth_scopes being requested. (Hashes in the serialized fields environment, mounts and runtime_constraints use normalized key order.)
+When a container request is "Committed", the system will try to find and reuse an existing Container with the same command, cwd, environment, output_path, container_image, mounts, secret_mounts, runtime_constraints, runtime_user_uuid, and runtime_auth_scopes being requested.
+
+* The serialized fields environment, mounts, and runtime_constraints are normalized when searching.
+* The system will also search for containers with minor variations in the keep_cache_disk and keep_cache_ram runtime_constraints that should not affect the result. This searches for other common values for those constraints, so a container that used a non-default value for these constraints may not be reused by later container requests that use a different value.
In order of preference, the system will use:
+
* The first matching container to have finished successfully (i.e., reached state "Complete" with an exit_code of 0) whose log and output collections are still available.
* The oldest matching "Running" container with the highest progress, i.e., the container that is most likely to finish first.
* The oldest matching "Locked" container with the highest priority, i.e., the container that is most likely to start first.