Added documentation on concurrent and conditional

execution

Author: renatof

.DS_Store

@@ -1,3 +1,27 @@
-# Conditional invocation
+# Conditional Invocation
 
-Conditional invocation
+FaaSr supports the conditional invocation of actions in the workflow. This is useful in workflows where actions may or may not execute depending on the _return value_ (true or false) of a predecessor.
+
+## Expressing conditional invocation in the workflow 
+
+Consider the example below, where the action `DownloadData` always invokes `TestData` unconditionally (black edges denote unconditional execution). Now suppose `TestData` invokes a user function (in R or Python) `my_test()` that returns either `True` or `False`. 
+
+Then, _depending on the return value of_ `my_test()`, either `ComputeT` is invoked (return value `True`, green edge), or `ComputeF` is invoked (return value `False`, red edge) - but not both.
+
+![alt text](conditional_example.png)
+
+Finally, the last action in the graph `ComputeNext` is invoked unconditionally. In effect, this implements the behavior of an if-then-else conditional execution in the workflow.
+
+## Constraints
+
+There are constraints that need to be observed when expressing conditional execution:
+
+- Cycles are not allowed (the workflow graph must still be a [DAG])
+- A node in a graph *cannot* have incident edges of different types (conditional and unconditional). 
+
+The example below shows an _invalid_ use of conditionals where `ComputeNext` has incident edges of different types:
+
+![alt text](conditional_disallowed.png)
+
+
+[DAG]: prog_model.md

docs/conditional.md

@@ -27,10 +27,10 @@ In summary:
 - You need an access key, secret key, and ARN to use Lambda in FaaSr.
 - You can access your access and secret keys, and your ARN from your [Amazon AWS console](https://console.aws.amazon.com/console/home).
 - Paste the access key and the secret key under the names `AWS_AccessKey` and `AWS_SecretKey`, respectively, as _Repository secrets_ in your _FaaSr-workflow_ as per the instructions in the [workflow repo] documentation
-- Past your ARN as `AWS_ARN` as _Repository secrets_ in your _FaaSr-workflow_
+- Paste your ARN as `AWS_ARN` as _Repository secrets_ in your _FaaSr-workflow_
 
 
-## OpenWHisk
+## OpenWhisk
 
 - You need an API key from your provider to configure for use in FaaSr
 - How you obtain this will depend on your cloud provider.

docs/conditional_disallowed.png

@@ -1,3 +1,30 @@
-# Concurrent invocation
+# Concurrent Actions
+
+FaaSr supports the invocation of multiple concurrent actions in the workflow. This is useful in workflows where the workflow developer is able to determine that multiple functions can safely execute in parallel - for example, when different functions operate on independent files/datasets There are two approaches possible to invoke actions to execute concurrently:
+
+- Multiple distinct actions explicitly invoked with edges from the same predecessor in the workflow DAG, or
+- A single action that is invoked _N times_, where _N_ is a configurable integer number, greater than 1; each invocation of the action is assigned a unique _rank_ (an integer from _1_ to _N_) that is available to the user function via the `faasr_rank` API
+
+## Multiple distinct actions
+
+Consider the example below, where the action `DownloadData` invokes three concurrent actions that are distinct and explicitly added to the workflow graph: `ComputeA`, `ComputeB`, and `ComputeC`:
+
+![alt text](distinct_concurrent.png)
+
+Each one of these actions can invoke a different user function concurrently. At the end, the action `Merge` executes the last user function, only after the three distinct actions `ComputeA`, `ComputeB`, and `ComputeC` have completed.
+
+## Ranked actions
+
+Ranked actions allows you to express concurrency with _multiple, parameterized invocations of the same user function_. Consider the workflow below, where the action `DownloadData` now invokes the _same_ action `ComputeRanked` three times, concurrently:
+
+![alt text](ranked_concurrent.png)
+
+Each concurrent `ComputeRanked` action invokes the _same user function_. Similarly to the previous example, at the end, the action `Merge` executes the last user function, only after all three `ComputeRanked` actions have completed.
+
+Inside the user function invoked by each `ComputeRanked` action, the `faasr_rank` API can be invoked to return a unique number (1, 2, or 3 in this example) that can be used to differentiate between invocations. As described in the [Python API] and [R API] documentation, `faasr_rank` allows the user function to determine the `maximum` rank (3 in this example) in addition to the `per-action` rank (1, 2, or 3). 
+
+This information can be used, for example, to select different file names, folders, or data subsets that each action operates on. It is the responsibility of the programmer to properly use the rank information to partition datasets for safe concurrent execution, depending on their workflow and application logic.
+
+[Python API]: py_api.md
+[R API]: r_api.md
 
-Concurrent invocation

docs/conditional_example.png

@@ -18,7 +18,7 @@ nav:
     - 'Registering workflows': 'register_workflow.md'
     - 'Invoking workflows': 'invoke_workflow.md'
     - 'Retrieving logs': 'logs.md'
-    - 'Concurrent invocation': 'rank.md'
+    - 'Concurrent actions and ranks': 'rank.md'
     - 'Conditional invocation': 'conditional.md'
     - 'Invocation IDs': 'invocationid.md'
     - 'Package dependences': 'dependences.md'