improve broadcast documentation

Author: oliver-sanders

src/dictionaries/words

@@ -12,6 +12,7 @@ basename
 baz
 boolean
 booleans
+broadcasted
 cfg
 changelog
 changelogs

src/tutorial/furthertopics/broadcast.rst

@@ -135,3 +135,14 @@ e.g::
 Stop the workflow::
 
    cylc stop tutorial-broadcast
+
+
+Further Reading
+---------------
+
+The :ref:`cylc-broadcast` section in the user guide contains more detail
+on broadcasts.
+
+The GUI contains an "Edit Runtime" utility which loads the task's configuration
+into a form. Any changes you make are then broadcasted to the task.
+See :ref:`interventions.edit-a-tasks-configuration`.

src/user-guide/running-workflows/cylc-broadcast.rst

@@ -0,0 +1,135 @@
+.. _cylc-broadcast:
+
+Cylc Broadcast
+==============
+
+Cylc "Broadcasts" allow us to override task's :cylc:conf:`[runtime]`
+settings within a running workflow.
+
+Broadcasts can target specific cycles, families or tasks.
+
+Broadcasts can be helpful for:
+
+* Quickly developing tasks without having to
+  :ref:`edit and reload the workflow configuration <interventions.edit-the-workflow-configuration>`.
+* Sending small amounts of data from a running task to other upcoming tasks (e.g. file paths).
+* Orchestrating production workflows from an external system.
+
+Broadcasts which target specific cycles will eventually be
+:ref:`expired <user_guide.broadcast.expiry>` when no longer needed.
+
+Otherwise, broadcasts last for the life of the workflow and will persist if
+the workflow is shutdown and restarted (unless manually "cleared").
+
+.. seealso::
+
+   :ref:`broadcast-tutorial`
+
+
+Issuing Broadcasts
+------------------
+
+CLI
+^^^
+
+Some examples of issuing broadcasts using the ``cylc broacast`` CLI command:
+
+.. code-block:: bash
+
+   # set or update the environment variable "ANSWER" for all tasks
+   cylc broadcast myworkflow -s '[environment]ANSWER=42'
+
+   # amend the directives for all tasks in the cycle "2000"
+   cylc broadcast myworkflow -p 2000 -s '[directives]--memory=2GB'
+
+   # change the platform all tasks in the family "FOO" will submit on
+   cylc broadcast myworkflow -n FOO -s 'platform=my-hpc'
+
+The ``cylc broadcast`` command can be run from within tasks as a means to
+communicate small amounts of data back to the scheduler for subsequent tasks to
+use. Note that this will not work for remote task platforms which have been
+configured to use polling -
+:cylc:conf:`global.cylc[platforms][<platform name>]communication method = poll`.
+
+For more information, run ``cylc broadcast --help``.
+
+
+GUI
+^^^
+
+Broadcasts can also be issued from the GUI in a similar way using the
+"Broadcast" command.
+
+Additionally, the GUI provides a utility called "Edit Runtime" which loads
+the tasks configuration into a form. Any changes you make are then broadcasted
+to the task:
+
+.. image:: ../interventions/edit-a-tasks-configuration.gui.gif
+   :width: 75%
+   :align: center
+
+|
+
+
+.. _user_guide.broadcast.expiry:
+
+Expiry
+------
+
+Broadcasts which target specific cycles will eventually expire (i.e. be
+deleted) as the workflow moves on. Otherwise they would gradually accumulate 
+over the life of the workflow (note broadcasts are persisted when the workflow
+restarts).
+
+
+Expiry Point
+^^^^^^^^^^^^
+
+Broadcasts are only expired after they are no longer required by tasks.
+The exact point at which a broadcast is expired depends on two things:
+
+* The oldest cycle in the workflow to contain
+  :term:`active tasks <active task>`.
+* The longest cycling :term:`recurrence` in the workflow.
+
+Broadcasts which are older than the oldest cycle point to contain active tasks
+*minus* the duration of the longest recurrence will be cleared.
+
+For example, for the following workflow:
+
+.. code-block:: cylc
+
+   [scheduling]
+       [[graph]]
+           P1Y = foo
+           P2Y = bar
+           P3Y = baz
+
+The longest cycling recurrence is ``P3Y``.
+
+If there were no more tasks left running in the cycle ``2000``, then broadcasts
+for cycles earlier than ``1997`` (``2000 - P3Y``) would be expired.
+
+This arrangement has been designed such that broadcasts should always be
+present for the previous instance of a task in case you want to re-run it.
+
+
+Broadcasting To Historical Cycles
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Broadcasts targeting historical cycles may be expired as soon as they are
+issued as the result of broadcast expiry.
+
+Broadcast expiry does not occur while the workflow is paused. If you want to
+broadcast to a historical cycle before re-running it, first pause the workflow,
+then trigger the tasks, then resume the workflow, e.g:
+
+.. code-block:: bash
+
+   cylc pause my-workflow
+   cylc broadcast my-workflow -p 2000 -s ...
+   cylc trigger my-workflow
+   cylc play my-workflow
+
+
+.. TODO: document sub-workflows

src/user-guide/running-workflows/dynamic-behaviour.rst

@@ -13,7 +13,7 @@ Running Workflows
    reflow
    workflow-run-modes
    scheduler-log-files
-   dynamic-behaviour
+   cylc-broadcast
    authentication-files
    workflow-databases
    advanced