A simple users guide overviewing the basic Cilk keywords and how to use them.

Author: neboat

src/doc/users-guide/basics-of-cilk-programming.md

@@ -0,0 +1,138 @@
+---
+title: Basics of Cilk programming
+eleventyNavigation:
+  order: -1
+---
+
+OpenCilk extends C and C++ with a few parallel keywords.  Programmers use these keywords to allow computations in the program to be executed in parallel.  The OpenCilk compiler and runtime system then efficiently execute those logically parallel computations on parallel processors.  This guide overviews the basic Cilk keywords — `cilk_spawn`, `cilk_scope`, `cilk_for`, and `cilk_sync` — as well as their basic usage.
+
+To use the Cilk keywords, include the `cilk/cilk.h` header file in your source code and compile and link your program with the `-fopencilk` flag.
+
+## Spawning and synchronizing tasks
+
+The `cilk_spawn` and `cilk_scope` keywords allow programmers to spawn and synchronize parallel computations, or ***tasks***.
+
+A `cilk_spawn` can be inserted before a function call to ***spawn*** that function call, which allows that call to execute in parallel with its ***continuation***, that is, the statements after the call.
+
+The `cilk_scope` keyword defines a lexical scope that ***synchronizes*** spawned tasks.  In particular, all tasks spawned within the scope must complete before the program execution leaves the scope.
+
+The following example shows how `cilk_spawn` and `cilk_scope` are used together to spawn and synchronize a parallel task.
+
+```cilkc
+#include <cilk/cilk.h>
+
+int fib(int n) {
+  if (n < 2)
+    return n;
+  int x, y;
+  cilk_scope {
+    x = cilk_spawn fib(n - 1);
+    y = fib(n - 2);
+  }
+  return x + y;
+}
+```
+
+In this example, the statement `x = cilk_spawn fib(n - 1)` spawns a task to compute `x = fib(n - 1)`.  The spawn allows this task to execute in parallel with the continuation of the spawn statement, which, in this example, consists only of the statement `y = fib(n - 2)`.  The `cilk_scope` ensures that the spawned computation of `x = fib(n - 1)` completes before `return x + y` reads the values of `x` and `y`.
+
+In this example, if `n` is sufficiently large, then the computations `fib(n - 1)` and `fib(n - 2)` can recursively spawn and synchronize their own subtasks.  As a result, this example `fib` routine can spawn a large number of parallel tasks.  OpenCilk takes advantage of these numerous parallel tasks to automatically schedule the computation efficiently on parallel computing hardware.
+
+## Parallel loops
+
+The `cilk_for` keyword provides a parallel loop construct.  A `cilk_for` keyword can be used in place of ordinary `for` in C/C++ to allow all of the iterations of the loop to execute in parallel.
+
+The following example shows how `cilk_for` can be used to parallelize a SAXPY computation.
+
+```cilkc
+#include <cilk/cilk.h>
+
+void saxpy(int n, float *z, const float a, const float *x, const float *y) {
+  cilk_for (int i = 0; i < n; ++i)
+    z[i] = a * x[i] + y[i];
+}
+```
+
+In this example, the `cilk_for` loop allows all `n` iterations of the loop over `i` to execute in parallel, which allows each entry `z[i]` is allowed to be computed in parallel.
+
+Cilk allows, and generally encourages, nesting of `cilk_for` loops, as in the following example.
+
+```cilkc
+#include <cilk/cilk.h>
+
+void square_matmul(double *C, const double *A, const double *B, size_t n) {
+  cilk_for (size_t i = 0; i < n; ++i) {
+    cilk_for (size_t j = 0; j < n; ++j) {
+      double sum = 0.0;
+      for (size_t k = 0; k < n; ++k)
+        sum += A[i * n + k] * B[k * n + j];
+      C[i * n + j] = sum;
+    }
+  }
+}
+```
+
+The outer `cilk_for` loop allows the `n` iterations over `i` to execute in parallel.  For each outer-loop-iteration `i`, the inner `cilk_for` loop allows the `n` iterations over `j` to execute in parallel.  Together, these two nested `cilk_for` loops allow all `n`$^2$ entries `C[i * n + j]` to be computed in parallel.
+
+## Mixing Cilk keywords and C/C++ code
+
+The Cilk keywords can be combined flexibly with each other and with standard C/C++ code.  The following synthetic example, inspired by real Cilk programs, demonstrates some of this flexibility.
+
+```cilkc
+#include <cilk/cilk.h>
+
+// Tree-node structure where each node contains two arrays of size `n` and up
+// to two children.
+struct node {
+  struct node *left_child;   // Might be NULL
+  struct node *right_child;  // Might be NULL
+  float *array_A, *array_B;
+  int n;
+};
+
+// Recursively walk the tree rooted at `root` to count the number of nodes in
+// the tree and to process all arrays at all nodes. 
+int count_and_process_tree(struct node *root) {
+  int left_count = 0;
+  int right_count = 0;
+  cilk_scope {
+    // Traverse the left and right children in parallel.
+    if (root->left_child)
+      left_count = cilk_spawn count_and_process_tree(root->left_child);
+    if (root->right_child)
+      right_count = cilk_spawn count_and_process_tree(root->right_child);
+
+    // Process the arrays at this node.
+    cilk_for (int i = 0; i < root->n; ++i) {
+      cilk_scope {
+        cilk_spawn process_A(root->array_A[i]);
+        process_B(root->array_B[i]);
+      }
+      combine(root->array_A[i], root->array_B[i]);
+    }
+  }
+  return left_count + right_count + 1;
+}
+```
+
+In this example, the `count_and_process_tree()` routine traverses a binary tree in parallel and processes arrays of elements at each node of that tree.  This example uses the Cilk keywords in several notable ways.
+
+- The recursive spawns of `count_and_process_tree()` process the left and right children of a node in parallel, if they exist.  These `cilk_spawn` statements are placed inside conditionals to ensure that the recursive spawns are performed only on non-null child nodes.
+- The recursive spawns of `count_and_process_tree()` allow the processing of these children to occur in parallel with the `cilk_for` that processes the arrays attached to the current node.
+- The `cilk_for` loop processes all `n` elements in the arrays `array_A` and `array_B` in parallel.
+- Each iteration `i` of the `cilk_for` loop uses `cilk_scope` and `cilk_spawn` to processes `array_A[i]` and `array_B[i]` separately in parallel, before those results are combined after the `cilk_scope`.
+- Each recursive spawn of `count_and_process_tree()` returns the number of nodes in the subtree rooted at that child node.  The outer `cilk_scope` ensures that both of these recursive spawns have completed before returning 1 plus the sum of those counts.
+
+## Dynamic synchronization
+
+OpenCilk also supports the `cilk_sync` statement for synchronizing spawned tasks within a function, `cilk_scope`, or `cilk_for`.  Although it is generally better programming practice to use `cilk_scope` for synchronization, the `cilk_sync` statement can be convenient in some situations.  In addition, the `cilk_sync` statement supports dynamic synchronization of spawned tasks, as the following snippet from an all-pairs-shortest-paths Cilk program demonstrates.
+
+```cilkc
+cilk_scope {
+  cilk_spawn recur(A, lda, im, i1, j0, j1, k0, k1);
+  if (overlaps(im, i1, k0, k1))
+    cilk_sync;
+  recur(A, lda, i0, im, j0, j1, k0, k1);
+}
+```
+
+In this example, the `cilk_spawn` allows the call to `recur()` to execute in parallel with the continuation, which starts at the call to `overlaps()`.  If this call returns true, then the `cilk_sync` statement will synchronize the spawned call to `recur()` before the second call to `recur()`, ensuring that the two calls execute sequentially.  Otherwise, the second call to `recur()` will be allowed to execute in parallel.  Finally, the `cilk_scope` ensures that both calls to `recur()` return before program execution leaves the scope.