%\pagebreak
\section{Doacross Loop Nest}
\label{sec:doacross}
\index{dependences!doacross loop nest}
\index{doacross loop nest!ordered construct@\kcode{ordered} construct}
\index{ordered construct@\kcode{ordered} construct!doacross loop nest}
\index{doacross loop nest!doacross clause@\kcode{doacross} clause}
\index{constructs!ordered@\kcode{ordered}}
\index{clauses!doacross@\kcode{doacross}}
\index{doacross clause@\kcode{doacross} clause}

An \kcode{ordered} clause can be used on a worksharing-loop construct with an integer
parameter argument to define the number of associated loops within 
a \plc{doacross loop nest} where cross-iteration dependences exist.
A \kcode{doacross} clause on an \kcode{ordered} construct within an \plc{ordered}
loop describes the dependences of the \plc{doacross} loops. 

In the code below, the \kcode{doacross(sink:\ucode{i-1})} clause defines an \ucode{i-1} 
to \ucode{i} cross-iteration dependence that specifies a wait point for 
the completion of computation from iteration \ucode{i-1} before proceeding 
to the subsequent statements. The \kcode{doacross(source:omp_cur_iteration)} 
or \kcode{doacross(source:)} clause indicates 
the completion of computation from the current iteration (\ucode{i}) 
to satisfy the cross-iteration dependence that arises from the iteration.
The \kcode{omp_cur_iteration} keyword is optional for the \kcode{source}
dependence type.
For this example the same sequential ordering could have been achieved 
with an \kcode{ordered} clause without a parameter on the worksharing-loop directive,
and a single \kcode{ordered} directive without the \kcode{doacross} clause
specified for the statement executing the \ucode{bar} function.

\cexample[5.2]{doacross}{1}

\ffreeexample[5.2]{doacross}{1}

\pagebreak
The following code is similar to the previous example but with 
the \plc{doacross loop nest} extended to two nested loops, \ucode{i} and \ucode{j},
as specified by the \kcode{ordered(\ucode{2})} clause on the worksharing-loop directive.
In the C/C++ code, the \ucode{i} and \ucode{j} loops are the first and
second associated loops, respectively, whereas
in the Fortran code, the \ucode{j} and \ucode{i} loops are the first and
second associated loops, respectively.
The \kcode{doacross(sink:\ucode{i-1,j})} and \kcode{doacross(sink:\ucode{i,j-1})} clauses in 
the C/C++ code define cross-iteration dependences in two dimensions from 
iterations (\ucode{i-1, j}) and (\ucode{i, j-1}) to iteration (\ucode{i, j}).  
Likewise, the \kcode{doacross(sink:\ucode{j-1,i})} and \kcode{doacross(sink:\ucode{j,i-1})} clauses 
in the Fortran code define cross-iteration dependences from iterations 
(\ucode{j-1, i}) and (\ucode{j, i-1}) to iteration (\ucode{j, i}).

\cexample[5.2]{doacross}{2}

\ffreeexample[5.2]{doacross}{2}


The following example shows an incorrect use of the \kcode{ordered}
directive with a \kcode{doacross} clause.  There are two issues with the code.  
The first issue is a missing \kcode{ordered doacross(source:)} directive,
which could cause a deadlock.  
The second issue is the \kcode{doacross(sink:\ucode{i+1,j})} and \kcode{doacross(sink:\ucode{i,j+1})} 
clauses define dependences on lexicographically later 
source iterations (\ucode{i+1, j}) and (\ucode{i, j+1}), which could cause 
a deadlock as well since they may not start to execute until the current iteration completes.

\cexample[5.2]{doacross}{3}

\ffreeexample[5.2]{doacross}{3}


The following example illustrates the use of the \kcode{collapse} clause for
a \plc{doacross loop nest}.  The \ucode{i} and \ucode{j} loops are the associated
loops for the collapsed loop as well as for the \plc{doacross loop nest}.
The example also shows a conforming usage of the \kcode{ordered} directive specifying a cross-iteration source
that is placed before a corresponding \kcode{ordered} directive specifying a
cross-iteration sink. There is no requirement that the source specification
must follow the sink specification in a given iteration.

\cexample[5.2]{doacross}{4}

\ffreeexample[5.2]{doacross}{4}