This is an automated email from the ASF dual-hosted git repository. heneveld pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/brooklyn-docs.git
commit 01d3de833bfebc1cd397d5a7253a9af226316d4d Author: Alex Heneveld <[email protected]> AuthorDate: Mon May 22 15:19:46 2023 +0100 add docs for `foreach` and `reducing` --- guide/blueprints/workflow/nested-workflow.md | 43 +++++++++++++++++++++++++++- guide/blueprints/workflow/steps/steps.yaml | 20 ++++++++++++- 2 files changed, 61 insertions(+), 2 deletions(-) diff --git a/guide/blueprints/workflow/nested-workflow.md b/guide/blueprints/workflow/nested-workflow.md index 7a09c08c..9ff9fc86 100644 --- a/guide/blueprints/workflow/nested-workflow.md +++ b/guide/blueprints/workflow/nested-workflow.md @@ -56,7 +56,7 @@ as follows: inclusive (so the string `1..4` is equivalent to the list `[1,2,3,4]`) The scratch variables `target` and `target_index` are available referring to to the specific target -and its 0-indexed position. +and its 0-indexed position. These names can be overridden with the `target_var_name` and `target_index_var_name` keys. Where a list is supplied, the result of the step is the list collecting the output of each sub-workflow. @@ -64,6 +64,45 @@ If a `condition` is supplied when a list is being used, the `workflow` step will and the `condition` will be applied to entries in the list. An example of this is included below. +The `foreach` type is a simplified variant of `workflow` when recursing over a list, +taking the same. + +#### Example + +``` +- step: foreach x in 1..3 + steps: + - return ${x} +``` + +The above loop will return `[1,2,3]`. + + +### Reducing + +Each nested workflow runs in its own scope and does not share workflow variables with the parent, +apart from values specified as `input`, or with other iterations of a loop. +Where it is desired to share variables across iterations, the key `reducing` can be supplied, +giving a map of variable names to be shared and their initial values. + +When `reducing`, the output of the workflow is this set of variables with their final values. + + +#### Example + +``` +- step: foreach x in 1..3 + reducing: + sum: 0 + steps: + - let sum = ${sum} + ${x} +``` + +The above loop will return `6`. + + +### Concurrency + By default nested workflows with list targets run sequentially over the entries, but this can be varied by setting `concurrency`. The following values are allowed: @@ -80,6 +119,8 @@ and always allowing 1. This might be used for example to upgrade a cluster in situ, leaving the larger of 10 instances or half the cluster alone, if possible. If the concurrency expression evaluates to 0, or to a negative number whose absolute value is larger than the number of values, the step will fail before executing, to ensure that if e.g. "-10" is specified when there are fewer than 10 items in the target list, the workflow does not run. (Use "max(1, -10)" to allow it to run 1 at a time if there are 10 or fewer.) +Concurrency cannot be specified when `reducing`. + #### Example This example invokes an effector on all children which are `service.isUp`, diff --git a/guide/blueprints/workflow/steps/steps.yaml b/guide/blueprints/workflow/steps/steps.yaml index 7212d032..f24f6b87 100644 --- a/guide/blueprints/workflow/steps/steps.yaml +++ b/guide/blueprints/workflow/steps/steps.yaml @@ -190,14 +190,32 @@ * `steps`: a list of steps to run, run in a separate context * `target`: an optional target specifier, an entity or input to the steps for the sub-workflow, or if a list, a list of entities or inputs to pass to multiple sub-workflows + * `target_var_name`: an optional variable name to set in nested workflows to refer to the element in the target, defaulting to `target` + * `target_index_var_name`: an optional variable name to set in nested workflows to refer to the index of the element in the target, if the target is a list, defaulting to `target_index` * `concurrency`: a specification for how many of the sub-workflows can be run in parallel, if given a list target; defaulting to one at a time, supporting a DSL as described [here](../nested-workflow.html) + * `reducing`: a map of variables to pass sequentially to each nested workflow instance, + with the values of those variables in the output or scratch for each nested workflow passed to the next nested workflow, + and the final set of those values being returned from this step for use in the calling workflow; + not permitted if `concurrency` is not static at `1` * `condition`: the usual condition settable on steps as described [here](../common.html) can be used, with one difference that if a target is specified, the condition is applied to it or to each entry in the list, to conditionally allow sub-workflows, and the workflow step itself will always run (i.e. the condition does not apply to the step itself if it has a target) * `replayable`: instructions to add or modify replay points, as described [here](../settings.html), for example `workflow replayable from here` * `retention`: instructions to modify workflow retention, as described [here](../settings.html) - output: the output from the last step in the nested workflow, or a list of such outputs if supplied a `target` list + output: if `reducing` is specified, the final value of those variables, + otherwise the output from the last step in the nested workflow or a list of such outputs if supplied a `target` list + + - name: foreach + summary: Runs nested workflow over a list using the specified variable name, equivalent to `workflow` when looping over a list + shorthand: '`foreach TARGET_VAR_NAME [ in TARGET ]`' + input: | + * `steps`: a list of steps to run, run in a separate context + * `target_var_name`: the name of the variable that should be set in nested workflows to refer to the element in the target list + * `target`: the list that should be looped over + * other input as per `workflow` + output: as per `workflow`, if `reducing` is specified, the final value of those variables, + otherwise the list of outputs from the last step of each nested workflow corresponding to an element in the `target` list - section_name: External Actions
