\pagebreak
\chapter{Program Control}
\label{sec:program_control}

Some specific and elementary concepts of controlling program execution are
illustrated in the examples of this chapter.  Control can be directly
managed with conditional control code (ifdef's with the \code{\_OPENMP} 
macro, and the Fortran sentinel (\code{!\$}) 
for conditionally compiling). The \code{if} clause on some constructs
can direct the runtime to ignore or alter the behavior of the construct.
Of course, the base-language \code{if} statements can be used to control the "execution" 
of stand-alone directives (such as \code{flush}, \code{barrier}, \code{taskwait}, 
and  \code{taskyield}).
However, the directives must appear in a block structure, and not as a substatement as shown in examples 1 and 2 of this chapter.

\bigskip
CANCELLATION

Cancellation (termination) of the normal sequence of execution for the threads in an OpenMP region can
be  accomplished with the \code{cancel} construct.  The construct uses a
\plc{construct-type-clause} to set the region-type to activate for the cancellation. 
That is, inclusion  of one of the \plc{construct-type-clause} names \code{parallel}, \code{for}, 
\code{do}, \code{sections} or \code{taskgroup} on the directive line 
activates the corresponding region.  
The \code{cancel} construct is activated by the first encountering thread,  and it
continues execution at the end of the named region.
The \code{cancel} construct is also a cancellation point for any other thread of the team 
to also continue execution at the end of the named region.  

Also, once the specified region has been activated for cancellation any thread that encounnters 
a \code{cancellation point} construct with the same named region (\plc{construct-type-clause}),
continues execution at the end of the region.

For an activated \code{cancel taskgroup} construct, the tasks that
belong to the taskgroup set of the innermost enclosing taskgroup region will be canceled. 

A task that encounters the cancel taskgroup construct continues execution at the end of its
task region. Any task of the taskgroup that has already begun execution will run to completion,
unless it encounters a \code{cancellation point}; tasks that have not begun execution "may" be
discarded as completed tasks.

\bigskip
CONTROL VARIABLES 

  Internal control variables (ICV) are used by implementations to hold values which control the execution
  of OpenMP regions.  Control (and hence the ICVs) may be set as implementation defaults, 
  or set and adjusted through environment variables, clauses, and API functions.  Many of the ICV control
  values are accessible through API function calls.  Also, initial ICV values are reported by the runtime
  if the \code{OMP\_DISPLAY\_ENV} environment variable has been set to \code{TRUE}. 

 %As an example, the \plc{nthreads-var} is the ICV that holds the number of threads
 %to be used in a \code{parallel} region.  It can be set with the \code{OMP\_NUM\_THREADS} environment variable, 
 %the \code{omp\_set\_num\_threads()} API function, or the \code{num\_threads} clause.  The default \plc{nthreads-var}
 %value is implementation defined.  All of the ICVs are presented in the \plc{Internal Control Variables} section
 %of the \plc{Directives} chapter of the OpenMP Specifications document.  Within the same document section, override 
 %relationships and scoping information can be found for applying user specifications and understanding the 
 %extent of the control.

\bigskip
NESTED CONSTRUCTS

Certain combinations of nested constructs are permitted, giving rise to a \plc{combined} construct
consisting of two or more constructs.  These can be used when the two (or several) constructs would be used
immediately in succession (closely nested). A combined construct can use the clauses of the component
constructs without restrictions.
A \plc{composite} construct is a combined construct which has one or more clauses with (an often obviously)
modified or restricted meaning, relative to when the constructs are uncombined. %%[appear separately (singly).

%The combined \code{parallel do} and \code{parallel for} constructs are formed by combining the \code{parallel}
%construct with one of the loops constructs \code{do} or \code{for}.  The
%\code{parallel do SIMD} and \code{parallel for SIMD} constructs are composite constructs (composed from
%the parallel loop constructs and the \code{SIMD} construct), because the \code{collapse} clause must
%explicitly address the ordering of loop chunking \plc{and} SIMD "combined" execution.

Certain nestings are forbidden, and often the reasoning is obvious.  Worksharing constructs cannot be nested, and
the \code{barrier} construct cannot be nested inside a worksharing construct, or a \code{critical} construct. 
Also, \code{target} constructs cannot be nested.  

The \code{parallel} construct can be nested, as well as the \code{task} construct.  The parallel
execution in the nested \code{parallel} construct(s) is control by the \code{OMP\_NESTED} and 
\code{OMP\_MAX\_ACTIVE\_LEVELS} environment variables, and the \code{omp\_set\_nested()} and 
\code{omp\_set\_max\_active\_levels()} functions.

More details on nesting can be found in the \plc{Nesting of Regions} of the \plc{Directives} 
chapter in the OpenMP Specifications document.
