Add support for Rocoto <hangdependency> element (#778)

Author: maddenp-cu

docs/sections/user_guide/cli/tools/rocoto/foobar-realize.out

@@ -13,6 +13,9 @@
     <command>/bin/true</command>
     <jobname>foo</jobname>
     <join>/some/path/slurm</join>
+    <hangdependency>
+      <sh name="ok">/bin/false</sh>
+    </hangdependency>
   </task>
   <task name="bar" cycledefs="default">
     <account>wrfruc</account>

docs/sections/user_guide/cli/tools/rocoto/foobar.yaml

@@ -16,6 +16,9 @@ workflow:
   tasks:
     task_foo:
       <<: *common
+      hangdependency:
+        sh_ok:
+          command: /bin/false
     task_bar:
       <<: *common
       dependency: {taskdep: {attrs: {task: foo}}}

docs/sections/user_guide/yaml/rocoto.rst

@@ -172,6 +172,7 @@ Let's dissect the following task example:
      envars:
        person: siri
      dependency:
+     hangdependency:
 
 Each task is named by its UW YAML key. Blocks under ``tasks:`` prefixed with ``task_`` will be named with what follows the prefix. In the example above the task will be named ``hello`` and will appear in the XML like this:
 
@@ -197,7 +198,7 @@ The name of the task can be any string accepted by Rocoto as a task name (includ
      <value>siri</value>
    </envar>
 
-``dependency:`` -- [Optional] Any number of dependencies accepted by Rocoto. This section is described in more detail below.
+``dependency:`` and ``hangdependency`` -- [Optional] Any number of dependencies accepted by Rocoto. This section is described in more detail below.
 
 The other keys not specifically mentioned here follow the same conventions as described in the :rocoto:`Rocoto<>` documentation.
 
@@ -274,6 +275,11 @@ The ``datadep_foo:`` and ``datadep_bar:`` UW YAML keys were named arbitrarily af
 
 This example also demonstrates the use of Rocoto's **boolean operator tags** in the structured UW YAML, e.g., ``<or>``, ``<not>``, etc. The structure follows the tree in the Rocoto XML language in that each of the subelements of the ``<and>`` tag translates to a subtree in UW YAML. Multiple boolean operator tags can be set at the same level, just as with any other tag type, by adding a descriptive suffix starting with an underscore. In the above example, the ``and:`` key could have equivalently been named ``and_data_files:`` to achieve an identical Rocoto XML result.
 
+``hangdependency:``
+^^^^^^^^^^^^^^^^^^^
+
+A ``hangdependency:`` block supports syntax identical to a ``dependency:`` block. Rocoto will interpret the resulting ``<hangdependency>`` XML element as specifying one or more conditions that, when satisfied, indicate that the task is hung and should be killed.
+
 Defining Metatasks
 ------------------
 

src/uwtools/resources/jsonschema/rocoto.jsonschema

@@ -401,6 +401,9 @@
         "exclusive": {
           "type": "string"
         },
+        "hangdependency": {
+          "$ref": "#/$defs/dependency"
+        },
         "jobname": {
           "$ref": "#/$defs/compoundTimeString"
         },

src/uwtools/rocoto.py

@@ -290,6 +290,8 @@ def _add_task(self, e: _Element, config: dict, name_attr: str) -> None:
             self._add_task_envar(e, name, value)
         if STR.dependency in config:
             self._add_task_dependency(e, config[STR.dependency])
+        if STR.hangdependency in config:
+            self._add_task_hangdependency(e, config[STR.hangdependency])
 
     def _add_task_dependency(self, e: _Element, config: dict) -> None:
         """
@@ -415,6 +417,17 @@ def _add_task_envar(self, e: _Element, name: str, value: str) -> None:
 
         self._add_compound_time_string(e, value, STR.value)
 
+    def _add_task_hangdependency(self, e: _Element, config: dict) -> None:
+        """
+        Add a <hangdependency> element to the <task>.
+
+        :param e: The parent element to add the new element to.
+        :param config: Configuration data for this element.
+        """
+        e = SubElement(e, STR.hangdependency)
+        for tag, subconfig in config.items():
+            self._add_task_dependency_child(e, subconfig, tag)
+
     def _add_workflow(self, config: dict) -> None:
         """
         Create the root <workflow> element.
@@ -559,6 +572,7 @@ class STR:
     envar: str = "envar"
     envars: str = "envars"
     exclusive: str = "exclusive"
+    hangdependency: str = "hangdependency"
     jobname: str = "jobname"
     join: str = "join"
     log: str = "log"

src/uwtools/tests/fixtures/hello_workflow.yaml

@@ -21,6 +21,9 @@ workflow:
         maxtries: 2
       account: "&ACCOUNT;"
       command: "echo account for $person is &ACCOUNT; && true"
+      hangdependency:
+        sh_false:
+          command: /bin/false
       jobname:
         cyclestr:
           attrs:
@@ -46,3 +49,6 @@ workflow:
           taskdep:
             attrs:
               task: hello
+        hangdependency:
+          sh_false:
+            command: /bin/false

src/uwtools/tests/test_schemas.py

@@ -1946,6 +1946,40 @@ def test_schema_rocoto_metatask_attrs():
     assert "'foo' is not of type 'integer'\n" in errors({"throttle": "foo"})
 
 
+def test_schema_rocoto_task_dependency():
+    errors = schema_validator("rocoto", "properties", "workflow", "properties", "tasks")
+    config = {
+        "task_foo": {
+            "command": "/bin/true",
+            "dependency": {
+                "sh_true": {
+                    "command": "/bin/true",
+                },
+            },
+            "cores": 1,
+            "walltime": "00:01:00",
+        }
+    }
+    assert not errors(config)
+
+
+def test_schema_rocoto_task_hangdependency():
+    errors = schema_validator("rocoto", "properties", "workflow", "properties", "tasks")
+    config = {
+        "task_foo": {
+            "command": "/bin/true",
+            "hangdependency": {
+                "sh_false": {
+                    "command": "/bin/false",
+                },
+            },
+            "cores": 1,
+            "walltime": "00:01:00",
+        }
+    }
+    assert not errors(config)
+
+
 def test_schema_rocoto_workflow_cycledef():
     errors = schema_validator("rocoto", "properties", "workflow", "properties", "cycledef")
     # Basic spec: