Examples_collapse.tex

\pagebreak
\section{The \code{collapse} Clause}
\label{sec:collapse}

In the following example, the \code{k} and \code{j} loops are associated with 
the loop construct. So the iterations of the \code{k} and \code{j} loops are 
collapsed into one loop with a larger iteration space, and that loop is then divided 
among the threads in the current team. Since the \code{i} loop is not associated 
with the loop construct, it is not collapsed, and the \code{i} loop is executed 
sequentially in its entirety in every iteration of the collapsed \code{k} and 
\code{j} loop. 

The variable \code{j} can be omitted from the \code{private}  clause when the 
\code{collapse} clause is used since it is implicitly private. However, if the 
\code{collapse} clause is omitted then \code{j} will be shared if it is omitted 
from the \code{private} clause. In either case, \code{k} is implicitly private 
and could be omitted from the \code{private}  clause.

\cexample{collapse}{1}

\fexample{collapse}{1}

In the next example, the \code{k} and \code{j} loops are associated with the 
loop construct. So the iterations of the \code{k} and \code{j} loops are collapsed 
into one loop with a larger iteration space, and that loop is then divided among 
the threads in the current team.

The sequential execution of the iterations in the \code{k} and \code{j} loops 
determines the order of the iterations in the collapsed iteration space. This implies 
that in the sequentially last iteration of the collapsed iteration space, \code{k} 
will have the value \code{2} and \code{j} will have the value \code{3}. Since 
\code{klast} and \code{jlast} are \code{lastprivate}, their values are assigned 
by the sequentially last iteration of the collapsed \code{k} and \code{j} loop. 
This example prints: \code{2 3}.

\cexample{collapse}{2}

\fexample{collapse}{2}

The next example illustrates the interaction of the \code{collapse} and \code{ordered} 
 clauses.

In the example, the loop construct has both a \code{collapse} clause and an \code{ordered} 
clause. The \code{collapse} clause causes the iterations of the \code{k} and 
\code{j} loops to be collapsed into one loop with a larger iteration space, and 
that loop is divided among the threads in the current team. An \code{ordered} 
clause is added to the loop construct, because an ordered region binds to the loop 
region arising from the loop construct.

According to Section 2.12.8 of the OpenMP 4.0 specification, 
a thread must not execute more than one ordered region that binds 
to the same loop region. So the \code{collapse} clause is required for the example 
to be conforming. With the \code{collapse} clause, the iterations of the \code{k} 
and \code{j} loops are collapsed into one loop, and therefore only one ordered 
region will bind to the collapsed \code{k} and \code{j} loop. Without the \code{collapse} 
clause, there would be two ordered regions that bind to each iteration of the \code{k} 
loop (one arising from the first iteration of the \code{j} loop, and the other 
arising from the second iteration of the \code{j} loop).

The code prints

\code{0 1 1}
\\
\code{0 1 2}
\\
\code{0 2 1}
\\
\code{1 2 2}
\\
\code{1 3 1}
\\
\code{1 3 2}

\cexample{collapse}{3}

\fexample{collapse}{3}