Introduction

This tutorial walks you through using cylc broadcast.

This changes task runtime configuration in a running suite, on-the-fly.

Purpose

cylc broadcast can be used to change any [runtime] setting during a suite's run.

You could invoke it on the command line (e.g. as a manual response to a failure) or use it in a task script (e.g. as part of an auto-recovery task that fixes other tasks).

cylc broadcast can also be used to communicate between tasks, where file-based communication is not appropriate. You should not normally need to use cylc broadcast in a task.

Task-based Example

Create a new suite (or just a new directory somewhere - e.g. in your homespace) containing a blank rose-suite.conf and a suite.rc file that looks like this:

Task-based Example Suite

[cylc]
    UTC mode = True # Ignore DST
[scheduling]
    initial cycle point = 20130101T00Z
    final cycle point = 20130105T00Z
    [[dependencies]]
        [[[R1]]]
            graph = startup => print_colour
        [[[T00]]]
            graph = print_colour[-P1D] => print_colour

Description

This sets up a standard cycling suite.

We have one daily task, print_colour, which prints some HTML output in a colour.

Runtime

It will need some runtime - add:

[runtime]
    [[print_colour]]
        script = """
            sleep 4
            echo "Today's colour is <span style='color:"$COLOUR"'>"$COLOUR"</span>"
        """
        [[[environment]]]
            COLOUR = green

Runtime - cylc broadcast

We need to set up the startup task now - replace [runtime] with:

[runtime]
    [[startup]]
        script = """
            cylc broadcast -p 20130102T0000Z -n print_colour -s [environment]COLOUR=blue $CYLC_SUITE_NAME
            cylc broadcast -p 20130104T0000Z -n print_colour -s [environment]COLOUR=red $CYLC_SUITE_NAME
            cylc broadcast -d $CYLC_SUITE_NAME
        """

Running It

The startup task will change the [[[environment]]] setting COLOUR of print_colour for the 20130102T00Z and the 20130104T00Z cycle times.

The cylc broadcast -d command will list the current broadcast settings.

Change directory to the root of the suite. Run the suite using:

rose suite-run

Results

Once the suite has run, you can see the results of the cylc broadcast by looking at print_colour's standard output file (job.out) in Rose Bush. Run:

rose suite-log

The output (job.out) of the print_colour tasks should have some green text when you click on the 'Tags' view in the top right, except for the 20130102T0000Z cycle time where it should be blue and 20130104T0000Z where it should be red.

CLI-based Example

You can also run cylc broadcast from the command line.

Remove the startup task script. Get rid of:

        script = """
            cylc broadcast -p 20130102T0000Z -n print_colour -s [environment]COLOUR=blue $CYLC_SUITE_NAME
            cylc broadcast -p 20130104T0000Z -n print_colour -s [environment]COLOUR=red $CYLC_SUITE_NAME
            cylc broadcast -d $CYLC_SUITE_NAME
        """

Cycle Time Extension

We should make the suite run a bit longer by increasing final cycle time:

    final cycle point = 20130125T00Z

Run CLI

Run the suite again, and while it runs we'll try and change settings using the cylc broadcast from the command line. You should replace $SUITE_ID with the suite name, and if the suite is not running on your local machine, you should add the option --host=$HOSTNAME where $HOSTNAME is the suite run host (look for will run on XXX in the suite run output).

While the suite is running, run:

cylc broadcast --host=$HOSTNAME -n print_colour -s [environment]COLOUR=orange $SUITE_ID

cylc broadcast continued

This will change the COLOUR setting of print_colour for all (subsequent) cycle times.

Try changing the colour to something else, e.g.:

cylc broadcast --host=HOSTNAME -n print_colour -s [environment]COLOUR=purple $SUITE_ID

Results

You can see the results of your command line changes by looking at the task's standard output in its job.out file with Rose Bush. Run:

rose suite-log

The colour output should change after the suite cycle times when you ran the commands.

Further Reading

For more information, run:

cylc help broadcast