Merge pull request #660 from oliver-sanders/clarify-runahead-limit

clarify runahead limit

Author: hjoliver

src/glossary.rst

@@ -68,10 +68,41 @@ Glossary
       don't get overwritten.
 
 
+   active
+   active task
+      An active task is a task which is near ready to run, in the process of
+      running, or which requires user intervention.
+
+      Active tasks are:
+
+      - Tasks which have some, but not all of their prerequisites satisfied.
+      - ``waiting`` tasks, that are actively waiting on:
+
+        - :term:`xtriggers <xtrigger>`.
+        - :ref:`internal queues <InternalQueues>`
+        - :ref:`runahead limit <RunaheadLimit>`
+      - ``preparing`` tasks - i.e. tasks in the process of submitting jobs
+      - ``submitted`` and ``running`` tasks - i.e. those with active jobs
+      - :term: `incomplete` tasks which have completed without satisfying all of their
+        :term:`required outputs <required output>`, (e.g. a failed task
+        where success was required).
+
+      Active tasks are in the ``n=0`` :term:`window <n-window>` which means they
+      will always be displayed in the GUI and Tui.
+
+      The distinction between active and non-active tasks is important for
+      the computing of the :term:`runahead limit`.
+
+
+   active cycle
+      A cycle is active if it contains any :term:`active tasks <active task>`.
+
+      Active cycles are counted towards the :term:`runahead limit`.
+
+
    window
    n-window
    active window
-   workflow window
    active task pool
       This is a :term:`graph`-based window or view of the workflow at runtime,
       including tasks out to ``n`` graph edges from current :term:`active
@@ -155,19 +186,6 @@ Glossary
          the same as :term:`workflow id`.
 
 
-   active
-   active task
-      An active task is a task in the submitted or running state.
-
-
-   active-waiting
-   active-waiting task
-      An active-waiting task is a task in the :term:`scheduler's <scheduler>`
-      ``n=0`` :term:`active window` that is ready to run according to its task
-      prerequisites, but is still waiting on a limiting mechanism such as a
-      :term:`clock trigger`, task :term:`hold`, or :term:`internal queue`.
-
-
    external trigger
    xtrigger
       External triggers allow :term:`tasks <task>` in the :term:`graph` to
@@ -1675,13 +1693,18 @@ Glossary
 
    runahead limit
    runahead
-      In a :term:`cycling workflow`, the runahead limit determines the maximum
-      number of consecutive cycle points that can be active at once.
+      In a :term:`cycling workflow`, the runahead limit determines how far
+      ahead of the oldest :ref:`active cycle point` the workflow is permitted
+      to run.
+
+      The "oldest active cycle point" is the first cycle in the workflow to contain
+      any :term:`active tasks <active task>` (e.g. running tasks).
 
       .. seealso::
 
          * :cylc:conf:`[scheduling]runahead limit`
          * :ref:`Runahead Limiting`
+         * :term:`active cycle`
 
 
    workflow completion

src/hyperlinks.rst.include

@@ -38,6 +38,9 @@
 .. _Cylc UI Server: https://github.com/cylc/cylc-uiserver
 .. _UI Server: https://github.com/cylc/cylc-uiserver
 
+
+.. Task Icons (inline)
+
 .. |task-waiting| image:: /img/task-job-icons/task-waiting.png
    :height: 18px
    :align: middle
@@ -71,6 +74,8 @@
    :align: middle
 
 
+.. Task Modifiers (inline)
+
 .. |task-held| image:: /img/task-job-icons/task-isHeld.png
    :height: 18px
    :align: middle
@@ -84,6 +89,23 @@
    :align: middle
 
 
+.. Task Modifiers (inline with modifiers as superscript)
+
+.. |task-held-super| image:: /img/task-job-icons/task-isHeld.png
+   :height: 24px
+   :align: middle
+
+.. |task-runahead-super| image:: /img/task-job-icons/task-isRunahead.png
+   :height: 24px
+   :align: middle
+
+.. |task-queued-super| image:: /img/task-job-icons/task-isQueued.png
+   :height: 24px
+   :align: middle
+
+
+.. Job Icons (inline)
+
 .. |job-submitted| image:: /img/task-job-icons/job-submitted.png
    :height: 18px
    :align: middle

src/img/n-window.gif

@@ -7,7 +7,6 @@ Running Workflows
    :maxdepth: 2
 
    scheduler-start-up
-   task-job-states
    tasks-jobs-ui
    retrying-tasks
    tracking-task-state

src/user-guide/running-workflows/index.rst

@@ -122,12 +122,14 @@ Triggering with No Active Flows
    same as if you had triggered the task just before the workflow completed.
 
 Special Case: Triggering ``n=0`` Tasks
-   Tasks in the ``n=0`` window are :term:`active`, :term:`active-waiting`, or
-   :term:`incomplete`. Their flow membership is already determined - that of
+   Tasks in the ``n=0`` window are :term:`active tasks <active task>`.
+   Their flow membership is already determined - that of
    the parent tasks that spawned them.
 
-   - Triggering an :term:`active task` has no effect (it is already triggered).
-   - Triggering an :term:`active-waiting task` queues it to run in the same flow.
+   - Triggering a task with a submitted or running job has no effect
+     (it is already triggered).
+   - Triggering other :term:`active tasks <active task>` e.g. (a waiting
+     task which is held) queues it to run in the same flow.
    - Triggering an :term:`incomplete task` queues it to re-run in the same flow.