@@ -220,6 +220,47 @@ To see this, take a look at the job script for one of the downstream tasks:
220
220
configuration.
221
221
222
222
223
+ .. _Sequential Xtriggers :
224
+
225
+ Sequential Xtriggers
226
+ ---------------------------
227
+
228
+ Parentless tasks (which don't depend on other tasks upstream in the graph)
229
+ naturally spawn out to the runahead limit. This may cause UI clutter, and
230
+ unnecessary xtrigger checking if the xtriggers would only be satisfied in
231
+ order.
232
+
233
+ You can use *sequential * xtriggers to avoid this problem: the next instance
234
+ of a task (i.e., at the next cycle point) that depends on a sequential xtrigger
235
+ will not be spawned until the previous xtrigger is satisfied. The
236
+ ``wall_clock `` xtrigger is sequential by default.
237
+
238
+ A trigger can be set as sequential in any or all of the following ways.
239
+
240
+ By setting the workflow-wide :cylc:conf: `flow.cylc[scheduling]sequential xtriggers `
241
+ (defaults to ``False ``) and/or keyword argument ``sequential `` to ``True ``/``False `` in
242
+ the xtrigger declaration:
243
+
244
+ .. literalinclude :: ../../workflows/xtrigger/sequential/flow.cylc
245
+ :language: cylc
246
+
247
+ When implementing a :ref: `custom xtrigger <Custom Trigger Functions >`, you can
248
+ set the default for the ``sequential `` keyword argument in the xtrigger function
249
+ definition itself:
250
+
251
+ .. code-block :: python
252
+
253
+ def my_xtrigger (my_in , my_out , sequential = True )
254
+
255
+ Xtrigger declaration takes precedence over function, and function over workflow
256
+ wide setting. So the above workflow definition would read:
257
+
258
+ - ``foo `` spawns out to the runahead limit.
259
+ - ``FAM `` spawns only when ``@upstream `` is satisfied.
260
+ - All associated xtriggers are checked and, as expected, their satisfaction
261
+ is a prerequisite to task readiness.
262
+
263
+
223
264
.. _Custom Trigger Functions :
224
265
225
266
Custom Trigger Functions
@@ -243,6 +284,7 @@ properties:
243
284
package.
244
285
245
286
- they can take arbitrary positional and keyword arguments
287
+ (except ``sequential ``, which is reserved - see :ref: `Sequential Xtriggers `)
246
288
- workflow and task identity, and cycle point, can be passed to trigger
247
289
functions by using string templates in function arguments (see below)
248
290
- integer, float, boolean, and string arguments will be recognized and
0 commit comments