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_r168511867
##########
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:
Review comment:
perhaps link to actions.md section on working with actions?
----------------------------------------------------------------
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
