12. Program Control

Basic concepts and mechanisms for directing and controlling a program compilation and execution are provided in this introduction and illustrated in subsequent examples.

CONDITIONAL COMPILATION and EXECUTION

Conditional compilation can be performed with conventional #ifdef directives in C, C++, and Fortran, and additionally with OpenMP sentinel (!$) in Fortran. The if clause on some directives can direct the runtime to ignore or alter the behavior of the construct. Of course, the base-language if statements can be used to control the execution of stand-alone directives (such as flush, barrier, taskwait, and taskyield). However, the directives must appear in a block structure, and not as a substatement. The metadirective and declare variant directives provide conditional selection of directives and routines for compilation (and use), respectively. The assume and requires directives provide invariants for optimizing compilation, and essential features for compilation and correct execution, respectively.

CANCELLATION

Cancellation (termination) of the normal sequence of execution for the threads in an OpenMP region can be accomplished with the cancel construct. The construct uses a construct-type-clause to set the region-type to activate for the cancellation. That is, inclusion of one of the construct-type-clause names parallel, for, do, sections or taskgroup on the directive line activates the corresponding region. The cancel construct is activated by the first encountering thread, and it continues execution at the end of the named region. The 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 cancellation point construct with the same named region ( construct-type-clause ), continues execution at the end of the region.

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

A task that encounters a 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 cancellation point; tasks that have not begun execution may be discarded as completed tasks.

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. Initial ICV values are reported by the runtime if the OMP_DISPLAY_ENV environment variable has been set to TRUE or VERBOSE.

NESTED CONSTRUCTS

Certain combinations of nested constructs are permitted, giving rise to combined constructs consisting of two or more directives. 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 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.

Certain nestings are forbidden, and often the reasoning is obvious. For example, worksharing constructs cannot be nested, and the barrier construct cannot be nested inside a worksharing construct, or a critical construct. Also, target constructs cannot be nested, unless the nested target is a reverse offload.

The parallel construct can be nested, as well as the task construct. The parallel execution in the nested parallel construct(s) is controlled by the OMP_MAX_ACTIVE_LEVELS environment variable, and the omp_set_max_active_levels routine. Use the omp_get_max_active_levels routine to determine the maximum levels provided by an implementation. As of OpenMP 5.0, use of the OMP_NESTED environment variable and the omp_set_nested routine has been deprecated.

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