improve broadcast documentation #871
Open
+148
−22
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
8 tasks
hjoliver
approved these changes
Sep 4, 2025
| * Quickly developing tasks without having to | ||
| :ref:`edit and reload the workflow configuration <interventions.edit-the-workflow-configuration>`. | ||
| * Sending small amounts of data from task to another (e.g. file paths). | ||
| * Orchestrating production workflows from an external system. |
There was a problem hiding this comment.
Can you explain what you mean a bit here?
There was a problem hiding this comment.
As a minimal example, our opps broadcasts HPC reservations into the workflows.
Broadcasts can enable a higher level monitoring / control system to reconfigure Cylc workflows on the fly.
There was a problem hiding this comment.
OK I think it might be good to say that in the docs. "Orchestrating production workflows from an external system" is going to sound intriguing to certain users, but they won't understand what it means IMO
oliver-sanders
force-pushed
the
broadcasts++
branch
from
f677aae to
583515d
Compare
8 tasks
hjoliver
requested changes
Sep 11, 2025
| Expiry Point | ||
| ^^^^^^^^^^^^ | ||
|
|
||
| Broadcasts are only expired after they are no longer required by tasks. |
There was a problem hiding this comment.
Suggested change
| Broadcasts are only expired after they are no longer required by tasks. | |
| Broadcasts expire once are they are no longer required by upcoming tasks. |
"Upcoming tasks" is clearer, and more justifiable (past tasks that haven't been re-triggered yet are not yet "upcoming").
| :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 |
There was a problem hiding this comment.
Suggested change
| Broadcasts which are older than the oldest cycle point to contain active tasks | |
| Broadcasts which are older than the oldest :term:`active cycle point` |
Comment on lines
+123
to
+125
| 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: |
There was a problem hiding this comment.
Suggested change
| 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: | |
| 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: |
Starting the second paragraph with "However" makes it immediately clear that we have a solution to the stated problem.
| Cylc Broadcast | ||
| ============== | ||
|
|
||
| Cylc "Broadcasts" allow us to override task's :cylc:conf:`[runtime]` |
There was a problem hiding this comment.
Suggested change
| Cylc "Broadcasts" allow us to override task's :cylc:conf:`[runtime]` | |
| Cylc "Broadcasts" allow us to override task :cylc:conf:`[runtime]` |
Comment on lines
+60
to
+61
| Broadcasts can also be issued from the GUI in a similar way using the | ||
| "Broadcast" command. |
There was a problem hiding this comment.
Suggested change
| Broadcasts can also be issued from the GUI in a similar way using the | |
| "Broadcast" command. | |
| Broadcasts can also be issued from the GUI in a similar way by choosing | |
| "Broadcast" from the task menu. |
Comment on lines
+80
to
+82
| 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). |
There was a problem hiding this comment.
Suggested change
| 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). | |
| deleted) as the workflow moves on, to avoid gradual accumulation | |
| (note broadcasts are persisted when the workflow restarts). |
Comment on lines
+113
to
+114
| 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. |
There was a problem hiding this comment.
Suggested change
| 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. | |
| This is designed to keep broadcasts as far back as the previous instance | |
| of each task, in case you want to re-run it. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Improve broadcast documentation and cover the broadcast expiry change in cylc/cylc-flow#6964
Requirements check-list
CONTRIBUTING.mdand added my name as a Code Contributor.