Merge pull request #6618 from hjoliver/doc-tweak-active

Fix a doc ref.

Author: hjoliver

cylc/flow/cfgspec/workflow.py

@@ -648,10 +648,10 @@ def get_script_common_text(this: str, example: Optional[str] = None):
         ''')
         Conf('runahead limit', VDR.V_STRING, 'P4', desc='''
             The runahead limit prevents a workflow from getting too far ahead
-            of the oldest cycle with :term:`active tasks <active task>`.
+            of the oldest :term:`active cycle`.
 
             A cycle is considered to be active if it contains any
-            :term:`active` tasks.
+            :term:`active tasks <active task>`.
 
             An integer interval value of ``Pn`` allows up to ``n+1`` cycles
             to be active at once.
@@ -668,11 +668,9 @@ def get_script_common_text(this: str, example: Optional[str] = None):
             ``P0``
                 Only one cycle can be active at a time.
             ``P2``
-                The scheduler will run up to two cycles ahead of the oldest
-                active cycle.
+                Allow up to two cycles ahead of the oldest active cycle.
             ``P3D``
-                The scheduler will run cycles up to three days of cycles ahead
-                of the oldest active cycle.
+                Allow cycles up to three days ahead of the oldest active cycle.
 
             .. seealso::
 
@@ -687,60 +685,42 @@ def get_script_common_text(this: str, example: Optional[str] = None):
         ''')
 
         with Conf('queues', desc='''
-            Configuration of internal queues of tasks.
+            Internal task queues to limit job activity.
 
-            This section will allow you to limit the number of simultaneously
-            :term:`active tasks <active task>` (submitted or running) by
-            assigning tasks to queues.
+            Queues delay job submission in member tasks, until the active
+            job count (for members) drops below the queue limit.
 
-            By default, a single queue called ``default`` is defined,
-            with all tasks assigned to it and no limit to the number of those
-            tasks which may be active.
+            There is a ``default`` queue with a configurable limit of 100, for
+            all tasks that are not assigned to other queues.
 
-            To use a single queue for the whole workflow, but limit the number
-            of active tasks, set :cylc:conf:`[default]limit`.
-
-            To add additional queues define additional sections:
+            You can define custom queues to limit job activity across other
+            groups of tasks.
 
             .. code-block:: cylc
 
                [[queues]]
-                   [[[user_defined_queue]]]
+                   [[[my_queue]]]
                        limit = 2
-                       members = TASK_FAMILY_NAME
+                       members = task1, task2, FAMILY1
 
             .. seealso::
 
                :ref:`InternalQueues`.
         '''):
             with Conf('<queue name>', desc='''
-                Section heading for configuration of a single queue.
+                Section for configuring a single queue.
             ''') as Queue:
                 Conf('limit', VDR.V_INTEGER, 0, desc='''
-                    The maximum number of :term:`active tasks <active task>`
-                    allowed at any one time, for this queue.
-
-                    If set to 0 this queue is not limited.
+                    The active job limit for this queue. 0 means no limit.
                 ''')
                 Conf('members', VDR.V_SPACELESS_STRING_LIST, desc='''
-                    A list of member tasks, or task family names to assign to
-                    this queue.
-
-                    Assigned tasks will automatically be removed
-                    from the default queue.
+                    A list of task or family names to assign to this queue.
                 ''')
             with Conf('default', meta=Queue, desc='''
-                The default queue for all tasks not assigned to other queues.
+                The default queue, for all tasks not assigned to other queues.
             '''):
                 Conf('limit', VDR.V_INTEGER, 100, desc='''
-                    Controls the total number of
-                    :term:`active tasks <active task>` in the default queue.
-
-                    .. seealso::
-
-                       - :cylc:conf:`flow.cylc[scheduling]
-                         [queues][<queue name>]limit`
-                       - :ref:`InternalQueues`
+                    The job limit for the ``default`` queue. 0 means no limit.
                 ''')
 
         with Conf('special tasks', desc='''

cylc/flow/etc/examples/extending-workflow/index.rst

@@ -3,7 +3,7 @@ Extending Workflow
 
 .. cylc-scope:: flow.cylc[scheduling]
 
-Sometimes we may run a workflow to :term:`completion <workflow completion>`,
+Sometimes we may run a workflow to :ref:`completion <workflow completion>`,
 but subsequently wish to run it for a few more cycles.
 
 With Cylc 7 this was often done by changing the `final cycle point` and

cylc/flow/scripts/set.py

@@ -67,8 +67,8 @@
   is the only xtrigger output and the default, so it can be omitted.)
 
 CLI Completion:
-  Cylc can auto-complete prerequisites and outputs for active tasks if you
-  specify the task in the command before attempting TAB-completion.
+  Cylc can auto-complete prerequisite and output names for tasks in the n=0
+  window, if you type the task name before attempting TAB-completion.
 
 Examples:
   # complete all required outputs of 3/bar:

cylc/flow/task_pool.py

@@ -276,7 +276,7 @@ def add_to_pool(self, itask) -> None:
         self.active_tasks.setdefault(itask.point, {})
         self.active_tasks[itask.point][itask.identity] = itask
         self.active_tasks_changed = True
-        LOG.debug(f"[{itask}] added to active task pool")
+        LOG.debug(f"[{itask}] added to the n=0 window")
 
         self.create_data_store_elements(itask)
 
@@ -893,7 +893,7 @@ def remove(self, itask: 'TaskProxy', reason: Optional[str] = None) -> None:
                 itask.flow_nums
             )
 
-        msg = f"removed from active task pool: {reason or 'completed'}"
+        msg = f"removed from the n=0 window: {reason or 'completed'}"
 
         if itask.is_xtrigger_sequential:
             self.xtrigger_mgr.sequential_spawn_next.discard(itask.identity)

tests/functional/hold-release/02-hold-on-spawn.t

@@ -34,7 +34,7 @@ workflow_run_ok "${TEST_NAME_BASE}-run" \
 cylc release "${WORKFLOW_NAME}//1/foo"
 # 1/foo should run and spawn 1/bar as waiting and held
 
-poll_grep_workflow_log -E '1/bar.* added to active task pool'
+poll_grep_workflow_log -E '1/bar.* added to the n=0 window'
 
 sqlite3 "${WORKFLOW_RUN_DIR}/log/db" \
     'SELECT cycle, name, status, is_held FROM task_pool' > task-pool.out

tests/functional/hold-release/08-hold.t

@@ -33,14 +33,14 @@ init_workflow "${TEST_NAME_BASE}" <<'__FLOW_CONFIG__'
     [[holdrelease]]
         script = """
             cylc__job__wait_cylc_message_started
-            cylc__job__poll_grep_workflow_log -E '1/foo.* added to active task pool'
-            cylc__job__poll_grep_workflow_log -E '1/bar.* added to active task pool'
-            cylc__job__poll_grep_workflow_log -E '1/cheese.* added to active task pool'
-            cylc__job__poll_grep_workflow_log -E '1/jam.* added to active task pool'
-            cylc__job__poll_grep_workflow_log -E '1/cat1.* added to active task pool'
-            cylc__job__poll_grep_workflow_log -E '1/cat2.* added to active task pool'
-            cylc__job__poll_grep_workflow_log -E '1/dog1.* added to active task pool'
-            cylc__job__poll_grep_workflow_log -E '1/dog2.* added to active task pool'
+            cylc__job__poll_grep_workflow_log -E '1/foo.* added to the n=0 window'
+            cylc__job__poll_grep_workflow_log -E '1/bar.* added to the n=0 window'
+            cylc__job__poll_grep_workflow_log -E '1/cheese.* added to the n=0 window'
+            cylc__job__poll_grep_workflow_log -E '1/jam.* added to the n=0 window'
+            cylc__job__poll_grep_workflow_log -E '1/cat1.* added to the n=0 window'
+            cylc__job__poll_grep_workflow_log -E '1/cat2.* added to the n=0 window'
+            cylc__job__poll_grep_workflow_log -E '1/dog1.* added to the n=0 window'
+            cylc__job__poll_grep_workflow_log -E '1/dog2.* added to the n=0 window'
             cylc hold "${CYLC_WORKFLOW_ID}//1/*FF"  # inexact fam
             cylc hold "${CYLC_WORKFLOW_ID}//1/TOAST"  # exact fam
             cylc hold "${CYLC_WORKFLOW_ID}//1/cat*"  # inexact tasks

tests/functional/hold-release/18-hold-cycle-globs/flow.cylc

@@ -23,9 +23,9 @@
 [runtime]
     [[holder]]
         script = """
-            cylc__job__poll_grep_workflow_log -E '19900101T0000Z/t1.* added to active task pool'
-            cylc__job__poll_grep_workflow_log -E '20100101T0000Z/t2.* added to active task pool'
-            cylc__job__poll_grep_workflow_log -E '20300101T0000Z/t3.* added to active task pool'
+            cylc__job__poll_grep_workflow_log -E '19900101T0000Z/t1.* added to the n=0 window'
+            cylc__job__poll_grep_workflow_log -E '20100101T0000Z/t2.* added to the n=0 window'
+            cylc__job__poll_grep_workflow_log -E '20300101T0000Z/t3.* added to the n=0 window'
             cylc hold "${CYLC_WORKFLOW_ID}//*/t*"
         """
     [[releaser]]

tests/functional/hold-release/19-no-reset-prereq-on-waiting/flow.cylc

@@ -16,7 +16,7 @@
         script = true
     [[holder]]
         script = """
-            cylc__job__poll_grep_workflow_log -E '1/t1.* added to active task pool'
+            cylc__job__poll_grep_workflow_log -E '1/t1.* added to the n=0 window'
             cylc hold "${CYLC_WORKFLOW_ID}//1/t1"
         """
     [[releaser]]

tests/functional/restart/22-hold/flow.cylc

@@ -17,7 +17,7 @@
     [[t1]]
         script = """
             if [[ "${CYLC_TASK_CYCLE_POINT}" == '2016' ]]; then
-                cylc__job__poll_grep_workflow_log -E '2016/t2.* added to active task pool'
+                cylc__job__poll_grep_workflow_log -E '2016/t2.* added to the n=0 window'
                 cylc hold "${CYLC_WORKFLOW_ID}//" //2016/t2 //2017/t2
                 cylc stop "${CYLC_WORKFLOW_ID}"
             else

tests/functional/runahead/06-release-update.t

@@ -27,7 +27,7 @@ CYLC_RUN_PID="$!"
 poll_workflow_running
 YYYY="$(date +%Y)"
 NEXT1=$(( YYYY + 1 ))
-poll_grep_workflow_log -E "${NEXT1}/bar.* added to active task pool"
+poll_grep_workflow_log -E "${NEXT1}/bar.* added to the n=0 window"
 
 # sleep a little to allow the datastore to update (`cylc dump` sees the
 # datastore) TODO can we avoid this flaky sleep somehow?