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_r168512662
##########
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.
Review comment:
this is not immediately clear:
```
+3624ad829d4044afa4ad829d40e4af60 tripleAndIncrement
+4f91f9ed0d874aaa91f9ed0d87baaa07 tripleAndIncrement
```
`4f9` is the outermost activation record, whereas `362` is the activation of
the conductor action itself. This is a little subtle and perhaps warrants a bit
more explanation.
----------------------------------------------------------------
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
