diff --git a/src/dictionaries/words b/src/dictionaries/words index d11139ea7c..c1c323fbb8 100644 --- a/src/dictionaries/words +++ b/src/dictionaries/words @@ -12,6 +12,7 @@ basename baz boolean booleans +broadcasted cfg changelog changelogs diff --git a/src/tutorial/furthertopics/broadcast.rst b/src/tutorial/furthertopics/broadcast.rst index d949c7c335..47956944f5 100644 --- a/src/tutorial/furthertopics/broadcast.rst +++ b/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`. diff --git a/src/user-guide/running-workflows/cylc-broadcast.rst b/src/user-guide/running-workflows/cylc-broadcast.rst new file mode 100644 index 0000000000..3ff3c4513c --- /dev/null +++ b/src/user-guide/running-workflows/cylc-broadcast.rst @@ -0,0 +1,134 @@ +.. _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 `. +* Sending small amounts of data from a running task to other upcoming tasks (e.g. file paths). +* Reconfiguring production workflows while they are running. + +Broadcasts which target specific cycles will eventually be +:ref:`expired ` 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][]communication method = poll`. + +For more information, run ``cylc broadcast --help``. + + +GUI +^^^ + +Broadcasts can also be issued from the GUI in a similar way by choosing +"Broadcast" from the task menu. + +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, to avoid gradual accumulation +(note broadcasts are persisted when the workflow restarts). + + +Expiry Point +^^^^^^^^^^^^ + +Broadcasts expire once are they are no longer required by upcoming 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 `. +* The longest cycling :term:`recurrence` in the workflow. + +Broadcasts which are older than the oldest :term:`active cycle point` +*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 is designed to keep broadcasts as far back as the previous instance +of each 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. + +However, broadcast expiry does not occur while the workflow is paused, so +you can pause the workflow, do the broadcast, trigger the tasks, and 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 diff --git a/src/user-guide/running-workflows/dynamic-behaviour.rst b/src/user-guide/running-workflows/dynamic-behaviour.rst deleted file mode 100644 index 0b892513b3..0000000000 --- a/src/user-guide/running-workflows/dynamic-behaviour.rst +++ /dev/null @@ -1,21 +0,0 @@ -.. _cylc-broadcast: - -Cylc Broadcast --------------- - -The ``cylc broadcast`` command overrides task :cylc:conf:`[runtime]` -settings in a running scheduler. You can think of it as communicating -new configuration settings (including information via environment variables) to -selected upcoming tasks via the scheduler. - -See ``cylc broadcast --help`` for detailed information. - -Broadcast settings targeting a specific cycle point expire as the workflow -moves on. Otherwise they persist for lifetime of the run, and across restarts, -unless cleared with another invocation of the command. - -.. seealso:: - - :ref:`broadcast-tutorial` - -.. TODO: document sub-workflows diff --git a/src/user-guide/running-workflows/index.rst b/src/user-guide/running-workflows/index.rst index ad3d2604d7..af4cdd4898 100644 --- a/src/user-guide/running-workflows/index.rst +++ b/src/user-guide/running-workflows/index.rst @@ -13,7 +13,7 @@ Running Workflows reflow workflow-run-modes scheduler-log-files - dynamic-behaviour + cylc-broadcast authentication-files workflow-databases advanced