doc: Update sdag manual to use serial instead of atomic
authorRamprasad Venkataraman <ramv@illinois.edu>
Fri, 26 Oct 2012 15:54:53 +0000 (10:54 -0500)
committerRamprasad Venkataraman <ramv@illinois.edu>
Fri, 26 Oct 2012 15:54:53 +0000 (10:54 -0500)
doc/charm++/sdag.tex

index 3cb747cea820e56c1d15b0198691ec48cdc74440..fc2786f2cfc88443e2ddb2f51a21da91af301fcd 100644 (file)
@@ -73,13 +73,17 @@ Structured Dagger. The basic constructs of Structured Dagger (SDAG) provide for
 define. These definitions appear in the {\tt .ci} file definition of the
 enclosing chare class as a `body' of an entry method following its signature.
 
 define. These definitions appear in the {\tt .ci} file definition of the
 enclosing chare class as a `body' of an entry method following its signature.
 
-The most basic construct in SDAG is the {\tt atomic} block. Atomic blocks
-contain sequential \CC code.  They're called atomic because the code within
+The most basic construct in SDAG is the {\tt serial} (aka the {\tt atomic}) block.
+Serial blocks
+contain sequential \CC code.  They're also called atomic because the code within
 them executes without returning control to the \charmpp\ runtime scheduler, and
 them executes without returning control to the \charmpp\ runtime scheduler, and
-thus avoiding interruption from incoming messages. Typically atomic blocks hold
+thus avoiding interruption from incoming messages. The keywords atomic and serial
+are synonymous, and you can find example programs that use atomic. However, we
+recommend the use of serial and are considering the deprecation of the atomic keyword.
+Typically serial blocks hold
 the code that actually deals with incoming messages in a {\tt when} statement,
 or to do local operations before a message is sent or after it's received. The
 the code that actually deals with incoming messages in a {\tt when} statement,
 or to do local operations before a message is sent or after it's received. The
-earlier example can be adapted to use atomic blocks as follows:
+earlier example can be adapted to use serial blocks as follows:
 \begin{center}
 \begin{alltt}
 // in .ci file
 \begin{center}
 \begin{alltt}
 // in .ci file
@@ -87,14 +91,14 @@ chare ComputeObject \{
   entry void ComputeObject();
   entry void startStep();
   entry void firstInput(Input i) \{
   entry void ComputeObject();
   entry void startStep();
   entry void firstInput(Input i) \{
-    atomic \{
+    serial \{
       first = i;
       if (--expectedMessageCount == 0)
         computeInteractions(first, second);
     \}
   \};
   entry void secondInput(Input j) \{
       first = i;
       if (--expectedMessageCount == 0)
         computeInteractions(first, second);
     \}
   \};
   entry void secondInput(Input j) \{
-    atomic \{
+    serial \{
       second = j;
       if (--expectedMessageCount == 0)
         computeInteractions(first, second);
       second = j;
       if (--expectedMessageCount == 0)
         computeInteractions(first, second);
@@ -131,12 +135,12 @@ Note that chare classes containing SDAG code must include a few additional decla
 in addition to inheriting from their {\tt CBase\_Foo} class, by incorporating the
 {\tt Foo\_SDAG\_CODE} generated-code macro in the class.
 
 in addition to inheriting from their {\tt CBase\_Foo} class, by incorporating the
 {\tt Foo\_SDAG\_CODE} generated-code macro in the class.
 
-Atomic blocks can also specify a textual `label' that will appear in traces, as
+Serial blocks can also specify a textual `label' that will appear in traces, as
 follows:
 \begin{center}
 \begin{alltt}
   entry void firstInput(Input i) \{
 follows:
 \begin{center}
 \begin{alltt}
   entry void firstInput(Input i) \{
-    atomic "process first" \{
+    serial "process first" \{
       first = i;
       if (--expectedMessageCount == 0)
         computeInteractions(first, second);
       first = i;
       if (--expectedMessageCount == 0)
         computeInteractions(first, second);
@@ -169,7 +173,7 @@ chare ComputeObject \{
   entry void startStep() \{
     when firstInput(Input first)
       when secondInput(Input second)
   entry void startStep() \{
     when firstInput(Input first)
       when secondInput(Input second)
-        atomic \{
+        serial \{
           computeInteractions(first, second);
         \}
   \};
           computeInteractions(first, second);
         \}
   \};
@@ -216,7 +220,7 @@ commas:
 entry void startStep() \{
   when firstInput(Input first),
        secondInput(Input second)
 entry void startStep() \{
   when firstInput(Input first),
        secondInput(Input second)
-    atomic \{
+    serial \{
       computeInteractions(first, second);
     \}
 \};
       computeInteractions(first, second);
     \}
 \};
@@ -260,7 +264,7 @@ chare ComputeObject \{
   entry void runForever() \{
     while(true) \{
       when firstInput(Input first),
   entry void runForever() \{
     while(true) \{
       when firstInput(Input first),
-           secondInput(Input second) atomic \{
+           secondInput(Input second) serial \{
           computeInteractions(first, second);
       \}
     \}
           computeInteractions(first, second);
       \}
     \}
@@ -298,7 +302,7 @@ chare ComputeObject \{
     for(iter = 0; iter < n; ++iter) \{
       // Match to only accept inputs for the current iteration
       when firstInput[iter](int a, Input first),
     for(iter = 0; iter < n; ++iter) \{
       // Match to only accept inputs for the current iteration
       when firstInput[iter](int a, Input first),
-           secondInput[iter](int b, Input second) atomic \{
+           secondInput[iter](int b, Input second) serial \{
         computeInteractions(first, second);
       \}
     \}
         computeInteractions(first, second);
       \}
     \}
@@ -336,7 +340,7 @@ SDAG also supports conditional execution of statements and blocks with {\tt if}
 statements. The syntax of SDAG {\tt if} statements matches that of C and
 C++. However, if one encounters a syntax error on correct-looking code in a
 loop or conditional statement, try assigning the condition expression to a
 statements. The syntax of SDAG {\tt if} statements matches that of C and
 C++. However, if one encounters a syntax error on correct-looking code in a
 loop or conditional statement, try assigning the condition expression to a
-boolean variable in an atomic preceding the statement and then testing that
+boolean variable in a serial block preceding the statement and then testing that
 boolean's value. This can be necessary because of the complexity of parsing C++
 code.
 
 boolean's value. This can be necessary because of the complexity of parsing C++
 code.
 
@@ -360,11 +364,11 @@ chare ComputeObject \{
   entry void startStep() \{
     overlap \{
       when firstInput(Input i)
   entry void startStep() \{
     overlap \{
       when firstInput(Input i)
-        atomic \{ first = preprocess(i); \}
+        serial \{ first = preprocess(i); \}
       when secondInput(Input j)
       when secondInput(Input j)
-        atomic \{ second = preprocess(j); \}
+        serial \{ second = preprocess(j); \}
      \}
      \}
-     atomic \{
+     serial \{
        computeInteractions(first, second);
      \}
   \};
        computeInteractions(first, second);
      \}
   \};
@@ -495,15 +499,15 @@ adding any significant overhead.
     entry void recv_first(Patch *first);
     entry void recv_second(Patch *first);
     entry void compute_object(MSG *msg)\{
     entry void recv_first(Patch *first);
     entry void recv_second(Patch *first);
     entry void compute_object(MSG *msg)\{
-      atomic \{
+      serial \{
          PatchManager->Get(msg->first_index,\dots);
          PatchManager->Get(msg->second_index,\dots);
       \}
       overlap \{
          PatchManager->Get(msg->first_index,\dots);
          PatchManager->Get(msg->second_index,\dots);
       \}
       overlap \{
-        when recv_first(Patch *first) atomic \{ filter(first); \}
-        when recv_second(Patch *second) atomic \{ filter(second); \}
+        when recv_first(Patch *first) serial \{ filter(first); \}
+        when recv_second(Patch *second) serial \{ filter(second); \}
       \}
       \}
-      atomic \{ computeInteractions(first, second); \}
+      serial \{ computeInteractions(first, second); \}
     \}
   \}
 \end{alltt}
     \}
   \}
 \end{alltt}
@@ -547,7 +551,7 @@ adding any significant overhead.
 
 <overlap-stmt> := "overlap" <body> 
 
 
 <overlap-stmt> := "overlap" <body> 
 
-<atomic-stmt> := "atomic" "\{" <\CC-code> "\}" 
+<atomic-stmt> := "serial" "\{" <\CC-code> "\}" 
 
 <if-stmt> := "if" "(" <int-expr> ")" <body> [<else-stmt>] 
 
 
 <if-stmt> := "if" "(" <int-expr> ")" <body> [<else-stmt>] 
 
@@ -604,7 +608,7 @@ SDAG constructs of the following kinds:
     \item {\tt if}, {\tt for}, and {\tt while} statements: these statements have
         the same meaning as the normal {\tt if}, {\tt for}, and {\tt while}
         loops in sequential \CC programs. This allows the programmer to use
     \item {\tt if}, {\tt for}, and {\tt while} statements: these statements have
         the same meaning as the normal {\tt if}, {\tt for}, and {\tt while}
         loops in sequential \CC programs. This allows the programmer to use
-        common control flow constructs outside the context of atomic blocks.
+        common control flow constructs outside the context of serial blocks.
 \end{itemize}
 
 \sdag{} code can be inserted into the .ci file for any array, group, or chare's entry methods.
 \end{itemize}
 
 \sdag{} code can be inserted into the .ci file for any array, group, or chare's entry methods.