rabbah commented on a change in pull request #3202: Support action
continuations in the controller
URL:
https://github.com/apache/incubator-openwhisk/pull/3202#discussion_r168513631
##########
File path: docs/conductors.md
##########
@@ -0,0 +1,253 @@
+# Conductor Actions
+
+Conductor actions make it possible to build and invoke a series of actions,
similar to sequences. However, whereas the components of a sequence action must
be specified before invoking the sequence, conductor actions can decide the
series of actions to invoke at run time.
+
+In this document, we specify conductor actions and illustrate them with a
simple example: a _tripleAndIncrement_ action.
+
+Suppose we define a _triple_ action in a source file `triple.js`:
+
+```javascript
+function main({ value }) { return { value: value * 3 } }
+```
+
+We create the action _triple_:
+
+```
+wsk action create triple triple.js
+```
+
+We define an _increment_ action in a source file `increment.js`:
+
+```javascript
+function main({ value }) { return { value: value + 1 } }
+```
+
+We create the action _increment_:
+
+```
+wsk action create increment increment.js
+```
+
+## Conductor annotation
+
+We define the _tripleAndIncrement_ action in a source file
`tripleAndIncrement.js`:
+
+```javascript
+function main(params) {
+ let step = params.$step || 0
+ delete params.$step
+ switch (step) {
+ case 0: return { action: 'triple', params, state: { $step: 1 } }
+ case 1: return { action: 'increment', params, state: { $step: 2 } }
+ case 2: return { params }
+ }
+}
+```
+
+We create a _conductor_ action by specifying the _conductor_ annotation:
+
+```
+wsk action create tripleAndIncrement tripleAndIncrement.js -a conductor true
+```
+
+A _conductor action_ is an action with a _conductor_ annotation with a value
that is not _falsy_, i.e., a value that is different from zero, null, false,
and the empty string.
+
+At this time, sequence actions cannot be conductor actions. The conductor
annotation on sequence actions is ignored.
+
+Because a conductor action is an action, it has all the attributes of an
action (name, namespace, default parameters, limits...) and it can be managed
as such, for instance using the `wsk action` CLI commands. It can be part of a
package or be a web action.
+
+In essence, the _tripleAndIncrement_ action builds a sequence of two actions
by encoding a program with three steps:
+
+- step 0: invoke the _triple_ action on the input dictionary,
+- step 1: invoke the _increment_ action on the output dictionary from step 1,
+- step 2: return the output dictionary from step 2.
+
+At each step, the conductor action specifies how to continue or terminate the
execution by means of a _continuation_. We explain continuations after
discussing invocation and activations.
+
+## Invocation
+
+A conductor action is invoked like a regular action, for instance:
+
+```
+wsk action invoke tripleAndIncrement -r -p value 3
+```
+```json
+{
+ "value": 10
+}
+```
+
+Blocking and non-blocking invocations are supported. As usual, a blocking
invocation may timeout before the completion of the invocation.
+
+## Activations
+
+One invocation of the conductor action results in multiple activations, for
instance:
+
+```
+wsk action invoke quadruple -p value 3
+```
+```
+ok: invoked /_/quadruple with id 4f91f9ed0d874aaa91f9ed0d87baaa07
+```
+```
+wsk activation list
+```
+```
+activations
+fd89b99a90a1462a89b99a90a1d62a8e tripleAndIncrement
+eaec119273d94087ac119273d90087d0 increment
+3624ad829d4044afa4ad829d40e4af60 tripleAndIncrement
+a1f58ade9b1e4c26b58ade9b1e4c2614 triple
+3624ad829d4044afa4ad829d40e4af60 tripleAndIncrement
+4f91f9ed0d874aaa91f9ed0d87baaa07 tripleAndIncrement
+```
+
+There are six activations in this example, one for the _tripleAndIncrement_
action we invoked plus five additional activations _caused_ by this invocation.
These five activations are:
+
+- one activation of the _triple_ action with input `{ value: 3 }` and output
`{ value: 9 }`,
+- one activation of the _increment_ action with input `{ value: 9 }` and
output `{ value: 10 }`,
+- three _secondary_ activations of the _tripleAndIncrement_ action.
+
+### Causality
+
+We say the invocation of the conductor action is the _cause_ of _component_
action invocations as well as _secondary_ activations of the conductor action.
These activations are _derived_ activations.
+
+The cause field of the _derived_ activation records is set to the id for the
_primary_ activation record.
+
+### Secondary activations
+
+The secondary activations of the conductor action are responsible for
orchestrating the invocations of the component actions.
+
+An invocation of a conductor action starts with a secondary activation and
alternates secondary activations of this conductor action with invocations of
the component actions. It normally ends with a secondary activation of the
conductor action. In our example, the five derived activations are interleaved
as follows:
+
+ 1. secondary _tripleAndIncrement_ activation,
+ 2. _triple_ activation,
+ 3. secondary _tripleAndIncrement_ activation,
+ 4. _increment_ activation,
+ 5. secondary _tripleAndIncrement_ activation.
+
+Intuitively, secondary activations of the conductor action decide which
component actions to invoke by running before, in-between, and after the
component actions.
+
+Only an internal error (invocation failure or timeout) may result in an even
number of derived activations.
+
+### Primary activation
+
+While secondary activations of the conductor action reflect executions of the
action code, the primary activation record for the invocation of a conductor
action does not. It is a synthetic record similar to the activation record of a
sequence action. Concretely in our example, the code in the main function of
the _tripleAndIncrement_ conductor action runs exactly three times since there
are three secondary activations.
+
+The primary activation record summarizes the series of derived activations:
Review comment:
suggestion: flip primary to come first, secondary section to come second.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
With regards,
Apache Git Services
