Commented the code of the set-spmd-linksign traversal.

src/libsac2c/concurrent/set_spmd_linksign.c

@@ -63,12 +63,16 @@ FreeInfo (info *info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param arg_node
- * @param arg_info
+ * @fn node *SSPMDLSarg(node *arg_node, info *arg_info)
  *
- * @return
+ *    @brief This function adds the LS of the corresponding ret or a new one
+ *           to the arg.
+ *
+ *    @param arg_node N_arg node
+ *    @param arg_info INFO structure
+ *
+ *    @return N_arg arg_node
  ******************************************************************************/
 
 node *
@@ -79,9 +83,11 @@ SSPMDLSarg (node *arg_node, info *arg_info)
     node *nret = NULL;
     nret = LUTsearchInLutPp (INFO_LUT (arg_info), ARG_AVIS (arg_node));
 
+    /* If current avis is in LUT, this argument is ret.*/
     if (nret != ARG_AVIS (arg_node)) {
         ARG_LINKSIGN (arg_node) = RET_LINKSIGN (nret);
-    } else {
+    } else /* New argument*/
+    {
         ARG_LINKSIGN (arg_node) = INFO_LS_NUM (arg_info);
         INFO_LS_NUM (arg_info) += 1;
     }
@@ -99,12 +105,22 @@ SSPMDLSarg (node *arg_node, info *arg_info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param arg_node
- * @param arg_info
+ * @fn node *SSPMDLSid(node *arg_node, info *arg_info)
+ *
+ *    @brief This function inserts withret-avis -> memval (default) into the
+ *           LUT if it is reached from through genarray, modarray, break or
+ *           propagate. Later when this node is reached through a N_return,
+ *           memval->ret is inserted in the LUT.
+ *           In this way we get the chain withrets -> memval -> rets.
+ *           The avis of the memvals and the avis of the functionargs is the
+ *           same so later when we reach the arguments, it is possible to find
+ *           the argument which belongs to a certain return.
+ *
+ *    @param arg_node N_id node
+ *    @param arg_info INFO struct
  *
- * @return
+ *    @return unchanged N_id node
  ******************************************************************************/
 
 node *
@@ -112,6 +128,9 @@ SSPMDLSid (node *arg_node, info *arg_info)
 {
     DBUG_ENTER ("SSPMDLSid");
 
+    /* if INFO_MEM is set, this is a Memval (genarray, modarray, break) or a
+     * default (propagate). In this case insert withret-avis -> memval into the
+     * LUT.*/
     if (INFO_MEM (arg_info)) {
         DBUG_PRINT ("SSPMDLS",
                     ("Insert %s->%s into LUT (id)", IDS_NAME (INFO_WITH_RETS (arg_info)),
@@ -120,6 +139,8 @@ SSPMDLSid (node *arg_node, info *arg_info)
           = LUTinsertIntoLutP (INFO_LUT (arg_info), IDS_AVIS (INFO_WITH_RETS (arg_info)),
                                ID_AVIS (arg_node));
     } else if (INFO_RETURNS (arg_info)) {
+        /* if this is an id of a return, get memval and insert memval -> ret into
+         * the LUT*/
         node *avis = NULL;
         DBUG_PRINT ("SSPMDLS",
                     ("Looking up arg for retexpr %s", AVIS_NAME (ID_AVIS (arg_node))));
@@ -135,12 +156,16 @@ SSPMDLSid (node *arg_node, info *arg_info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param arg_node
- * @param arg_info
+ * @fn SSPMDLSexprs(node *arg_node, info *arg_info)
  *
- * @return
+ *    @brief This function just checks if this is a return-expression. If this
+ *           is the case we have to traverse further.
+ *
+ *    @param arg_node N_exprs node
+ *    @param arg_info INFO structure
+ *
+ *    @return unchanged N_exprs node
  ******************************************************************************/
 
 node *
@@ -148,6 +173,8 @@ SSPMDLSexprs (node *arg_node, info *arg_info)
 {
     DBUG_ENTER ("SSPMDLSexprs");
 
+    /* As we are just adding linksigns to arguments and rets, we just have to
+     * traverse further if this is a return-expression.*/
     if (INFO_RETURNS (arg_info)) {
         EXPRS_EXPR (arg_node) = TRAVdo (EXPRS_EXPR (arg_node), arg_info);
         if (EXPRS_NEXT (arg_node) != NULL) {
@@ -161,12 +188,18 @@ SSPMDLSexprs (node *arg_node, info *arg_info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param arg_node
- * @param arg_info
+ * @fn node *SSPMDLSreturn(node *arg_node, info *arg_info)
+ *
+ *    @brief This function just sets the flag "INFO_RETURN" which indicates
+ *           in the N_expr node that it is reached from a N_return node because
+ *           this is the only case in which we have to traverse further into
+ *           the expression.
  *
- * @return
+ *    @param arg_node N_return node
+ *    @param arg_info INFO structure
+ *
+ *    @return unchanged N_return node
  ******************************************************************************/
 
 node *
@@ -185,12 +218,17 @@ SSPMDLSreturn (node *arg_node, info *arg_info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param arg_node
- * @param arg_info
+ * @fn node *SSPMDLSpropagate(node *arg_node, info *arg_info)
+ *
+ *    @brief This function traverses into the default of the propagate and in
+ *           case of further withops shifts the INFO_WITH_RETS one position
+ *           further befor traversing into the next op.
  *
- * @return
+ *    @param arg_node N_propagate node
+ *    @param arg_info INFO structure
+ *
+ *    @return unchanged N_propagate node
  ******************************************************************************/
 
 node *
@@ -204,6 +242,11 @@ SSPMDLSpropagate (node *arg_node, info *arg_info)
 
     INFO_MEM (arg_info) = FALSE;
 
+    /* as we have to find out each pair of indirectly connected function
+     * arguments and function returns, we try to keep track of the variable
+     * change which is caused by the with loop.
+     * Therefor we traverse through all withops and shift the returns of the
+     * withloop parallel to this traversing.*/
     if (PROPAGATE_NEXT (arg_node) != NULL) {
         INFO_WITH_RETS (arg_info) = IDS_NEXT (INFO_WITH_RETS (arg_info));
         DBUG_ASSERT (INFO_WITH_RETS (arg_info) != NULL, "#ids != #with-returns!");
@@ -214,12 +257,17 @@ SSPMDLSpropagate (node *arg_node, info *arg_info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param arg_node
- * @param arg_info
+ * @fn node *SSPMDLSgenarray(node *arg_node, info *arg_info)
+ *
+ *    @brief This function traverses into the memval of genarray and in case
+ *           of further withops shifts the INFO_WITH_RETS one position further
+ *           further befor traversing into the next op.
  *
- * @return
+ *    @param arg_node N_genarray node
+ *    @param arg_info INFO structure
+ *
+ *    @return unchanged N_genarray node
  ******************************************************************************/
 
 node *
@@ -233,6 +281,11 @@ SSPMDLSgenarray (node *arg_node, info *arg_info)
 
     INFO_MEM (arg_info) = FALSE;
 
+    /* as we have to find out each pair of indirectly connected function
+     * arguments and function returns, we try to keep track of the variable
+     * change which is caused by the with loop.
+     * Therefor we traverse through all withops and shift the returns of the
+     * withloop parallel to this traversing.*/
     if (GENARRAY_NEXT (arg_node) != NULL) {
         INFO_WITH_RETS (arg_info) = IDS_NEXT (INFO_WITH_RETS (arg_info));
         DBUG_ASSERT (INFO_WITH_RETS (arg_info) != NULL, "#ids != #with-returns!");
@@ -243,12 +296,17 @@ SSPMDLSgenarray (node *arg_node, info *arg_info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param arg_node
- * @param arg_info
+ * @fn node *SSPMDLSmodarray(node *arg_node, info *arg_info)
+ *
+ *    @brief This function traverses into the memval of the modarray and in
+ *           case of further withops shifts the INFO_WITH_RETS one position
+ *           further befor traversing into the next op.
+ *
+ *    @param arg_node N_modarray node
+ *    @param arg_info INFO structure
  *
- * @return
+ *    @return unchanged N_modarray node
  ******************************************************************************/
 
 node *
@@ -262,6 +320,11 @@ SSPMDLSmodarray (node *arg_node, info *arg_info)
 
     INFO_MEM (arg_info) = FALSE;
 
+    /* as we have to find out each pair of indirectly connected function
+     * arguments and function returns, we try to keep track of the variable
+     * change which is caused by the with loop.
+     * Therefor we traverse through all withops and shift the returns of the
+     * withloop parallel to this traversing.*/
     if (MODARRAY_NEXT (arg_node) != NULL) {
         INFO_WITH_RETS (arg_info) = IDS_NEXT (INFO_WITH_RETS (arg_info));
         DBUG_ASSERT (INFO_WITH_RETS (arg_info) != NULL, "#ids != #with-returns!");
@@ -272,12 +335,17 @@ SSPMDLSmodarray (node *arg_node, info *arg_info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param arg_node
- * @param arg_info
+ * @fn node *SSPMDLSbreak(node *arg_node, info *arg_info)
  *
- * @return
+ *    @brief This function traverses into the memval of the break and in case
+ *           of further withops shifts the INFO_WITH_RETS one position further
+ *           befor traversing into the next op.
+ *
+ *    @param arg_node N_break node
+ *    @param arg_info INFO structure
+ *
+ *    @return unchanged N_break node
  ******************************************************************************/
 
 node *
@@ -291,6 +359,11 @@ SSPMDLSbreak (node *arg_node, info *arg_info)
 
     INFO_MEM (arg_info) = FALSE;
 
+    /* as we have to find out each pair of indirectly connected function
+     * arguments and function returns, we try to keep track of the variable
+     * change which is caused by the with loop.
+     * Therefor we traverse through all withops and shift the returns of the
+     * withloop parallel to this traversing.*/
     if (BREAK_NEXT (arg_node) != NULL) {
         INFO_WITH_RETS (arg_info) = IDS_NEXT (INFO_WITH_RETS (arg_info));
         DBUG_ASSERT (INFO_WITH_RETS (arg_info) != NULL, "#ids != #with-returns!");
@@ -301,12 +374,16 @@ SSPMDLSbreak (node *arg_node, info *arg_info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param arg_node
- * @param arg_info
+ * @fn node *SSPMDLSwith2(node *arg_node, info *arg_info)
+ *
+ *    @brief This function just traverses further into the withops as we are
+ *           just interested in the MEMVALs and DEFAULTs.
+ *
+ *    @param arg_node N_with2 node
+ *    @param arg_info INFO structure
  *
- * @return
+ *    @return unchanged N_with2 node
  ******************************************************************************/
 
 node *
@@ -323,12 +400,16 @@ SSPMDLSwith2 (node *arg_node, info *arg_info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param arg_node
- * @param arg_info
+ * @fn node *SSPMDLSlet(node *arg_node, info *arg_info)
  *
- * @return
+ *    @brief This function keeps the LHS of the let in the INFO structure just
+ *           in case of a RHS with-loop.
+ *
+ *    @param arg_node N_let node
+ *    @param arg_info INFO structure
+ *
+ *    @return unchanged N_let node
  ******************************************************************************/
 
 node *
@@ -336,7 +417,8 @@ SSPMDLSlet (node *arg_node, info *arg_info)
 {
     DBUG_ENTER ("SSPMDLSlet");
 
-    /* Keep LHS, if RHS is withloop, it is needed.*/
+    /* Keep LHS, if RHS is withloop, it is needed to associate it to the
+     * corresponding memvals, respectively defaults.*/
     INFO_WITH_RETS (arg_info) = LET_IDS (arg_node);
 
     LET_EXPR (arg_node) = TRAVdo (LET_EXPR (arg_node), arg_info);
@@ -345,12 +427,15 @@ SSPMDLSlet (node *arg_node, info *arg_info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param arg_node
- * @param arg_info
+ * @fn node *SSPMDLSret(node *arg_node, info *arg_info)
+ *
+ *    @brief This function sets the linksine of the current function ret.
  *
- * @return
+ *    @param arg_node N_ret node
+ *    @param arg_info INFO structure
+ *
+ *    @return N_ret node
  ******************************************************************************/
 
 node *
@@ -377,12 +462,17 @@ SSPMDLSret (node *arg_node, info *arg_info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param arg_node
- * @param arg_info
+ * @fn node *SSPMDLSfundef(node *arg_node, info *arg_info)
+ *
+ *    @brief This function traverses the different parts of the fundef in the
+ *           right order to keep track of the pairs of corresponding
+ *           args/returns.
  *
- * @return
+ *    @param arg_node N_fundef node
+ *    @param arg_info INFO structure
+ *
+ *    @return unchanged N_fundef node
  ******************************************************************************/
 
 node *
@@ -418,12 +508,15 @@ SSPMDLSfundef (node *arg_node, info *arg_info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param arg_node
- * @param arg_info
+ * @fn node *SSPMDLSmodule(node *arg_node, info *arg_info)
+ *
+ *    @brief This function just initializes the LUT.
  *
- * @return
+ *    @param arg_node N_module node
+ *    @param arg_info INFO structure
+ *
+ *    @return unchanged N_module node
  ******************************************************************************/
 
 node *
@@ -443,11 +536,14 @@ SSPMDLSmodule (node *arg_node, info *arg_info)
 }
 
 /** <!-- ****************************************************************** -->
- * @brief
  *
- * @param syntax_tree
+ * @fn node *SSPMDLSdoSetSpmdLinksign(node *syntax_tree)
+ *
+ *    @brief This function triggers the traversal.
+ *
+ *    @param syntax_tree N_module node
  *
- * @return
+ *    @return syntax tree with LS pragmas on SPMD functionsparams and rets.
  ******************************************************************************/
 
 node *