Directive Format

| OPENMP API Specification: "Version 5.2 -- GIT rev 95b2e3a44"

3.1 Directive Format

This section deﬁnes several categories of directives and constructs. OpenMP directives are speciﬁed with a directive-speciﬁcation. A directive-speciﬁcation consists of the directive-speciﬁer and any clauses that may optionally be associated with the OpenMP directive:

 
directive-speciﬁer [[,] clause[ [,] clause] ... ]

The directive-speciﬁer is:

 
directive-name

or for argument-modiﬁed directives:

 
directive-name[(directive-arguments)]

White space in a directive-name is not optional.

Some OpenMP directives specify a paired end directive, where the directive-name of the paired end directives is:

If directive-name starts with begin, the end-directive-name replaces begin with end
otherwise it is end directive-name unless otherwise speciﬁed.

The directive-speciﬁcation of a paired end directive may include one or more optional end-clause:

 
directive-speciﬁer [[,] end-clause[ [,] end-clause]...]

where end-clause has the end-clause property, which explicitly allows it on a paired end directive.

An OpenMP directive may be speciﬁed as a pragma directive:

 
#pragma omp directive-speciﬁcation new-line

or a pragma operator:

 
_Pragma("omp directive-speciﬁcation")

The use of omp as the ﬁrst preprocessing token of a pragma directive is reserved for OpenMP directives that are deﬁned in this speciﬁcation. The use of ompx as the ﬁrst preprocessing token of a pragma directive is reserved for implementation-deﬁned extensions to the OpenMP directives.

In this directive, directive-name is depobj, directive-arguments is o. directive-speciﬁer is depobj(o) and directive-speciﬁcation is depobj(o) depend(inout: d).

 
#pragma omp depobj(o) depend(inout: d)

White space can be used before and after the #. Preprocessing tokens in directive-speciﬁcation of #pragma and _Pragma pragmas are subject to macro expansion.

In C++11 and higher, an OpenMP directive may be speciﬁed as a C++ attribute speciﬁer:

 
[[ omp :: directive-attr ]]

 
[[ using omp : directive-attr ]]

where directive-attr is

 
directive( directive-speciﬁcation )

 
sequence( [omp::]directive-attr [[, [omp::]directive-attr] ... ] )

Multiple attributes on the same statement are allowed. Attribute directives that apply to the same statement are unordered unless the sequence attribute is speciﬁed, in which case the right-to-left ordering applies. The omp:: namespace qualiﬁer within a sequence attribute is optional. The application of multiple attributes in a sequence attribute is ordered as if each directive had been speciﬁed as a pragma directive on subsequent lines.

This example shows the expected transformation:

 
[[ omp::sequence(directive(parallel), directive(for)) ]] 
for(...) {} 
// becomes 
#pragma omp parallel 
#pragma omp for 
for(...) {}

The use of omp as the attribute namespace of an attribute speciﬁer, or as the optional namespace qualiﬁer within a sequence attribute, is reserved for OpenMP directives that are deﬁned in this speciﬁcation. The use of ompx as the attribute namespace of an attribute speciﬁer, or as the optional namespace qualiﬁer within a sequence attribute, is reserved for implementation-deﬁned extensions to the OpenMP directives.

The pragma and attribute forms are interchangeable for any OpenMP directive. Some OpenMP directives may be composed of consecutive attribute speciﬁers if speciﬁed in their syntax. Any two consecutive attribute speciﬁers may be reordered or expressed as a single attribute speciﬁer, as permitted by the base language, without changing the behavior of the OpenMP directive.

Directives are case-sensitive. Each expression used in the OpenMP syntax inside of a clause must be a valid assignment-expression of the base language unless otherwise speciﬁed.

Directives may not appear in constexpr functions or in constant expressions.

An OpenMP directive for Fortran is speciﬁed with a stylized comment as follows:

 
sentinel directive-speciﬁcation

All OpenMP compiler directives must begin with a directive sentinel. The format of a sentinel diﬀers between ﬁxed form and free form source ﬁles, as described in Section 3.1.1 and Section 3.1.2. In order to simplify the presentation, free form is used for the syntax of OpenMP directives for Fortran throughout this document, except as noted.

Directives are case insensitive. Directives cannot be embedded within continued statements, and statements cannot be embedded within directives. Each expression used in the OpenMP syntax inside of a clause must be a valid expression of the base language unless otherwise speciﬁed.

A directive may be categorized as one of the following:

meta
declarative
executable
informational
utility
subsidiary

Base language code can be associated with directives. The directive’s association can be categorized as:

none
block-associated
loop-associated
declaration-associated
delimited
separating

A directive and its associated base language code constitute a syntactic formation that follows the syntax given below. The end-directive in a speciﬁed formation refers to the paired end directive for the directive. An OpenMP construct is a formation for which the directive is executable.

Directives with an association of none are not associated with any base language code. The resulting formation therefore has the following syntax:

 
directive

Formations that result from a block-associated directive have the following syntax:

 
directive 
  structured-block

 
directive 
  structured-block 
[end-directive]

If structured-block is a loosely structured block, end-directive is required. If structured-block is a strictly structured block, end-directive is optional. An end-directive that immediately follows a directive and its associated strictly structured block is always paired with that directive.

Loop-associated directives are block-associated directives for which the associated structured-block is loop-nest, a canonical loop nest.

For a loop-associated directive, the paired end directive is optional.

Formations that result from a declaration-associated directive have the following syntax:

 
declaration-associated-speciﬁcation

where declaration-associated-speciﬁcation is either:

 
directive 
  function-deﬁnition-or-declaration

or:

 
directive 
declaration-associated-speciﬁcation

In all cases the directive is associated with the function-deﬁnition-or-declaration.

The formation that results from a declaration-associated directive in Fortran has the same syntax as the formation for a directive with an association of none.

If a directive appears in the speciﬁcation part of a module then the behavior is as if that directive appears after any references to that module.

The formation that results from a delimited directive has the following syntax:

 
directive 
  base-language-code 
end-directive

Separating directives may be used to separate a structured-block into multiple structured-block-sequences.

Separating directives and the containing structured block have the following syntax:

 
structured-block-sequence 
directive 
structured-block-sequence 
[directive 
structured-block-sequence ...]

wrapped in a single compound statement for C/C++ or optionally wrapped in a single BLOCK construct for Fortran.

Restrictions

Restrictions to directive format are as follows:

Orphaned separating directives are prohibited. That is, the separating directives must appear within the structured block associated with the same construct with which it is associated and must not be encountered elsewhere in the region of that associated construct.
A stand-alone directive may be placed only at a point where a base language executable statement is allowed.

∙ OpenMP directives, except simd and declarative directives, may not appear in pure procedures. ∙ OpenMP directives may not appear in the WHERE, FORALL or DO CONCURRENT constructs.

∙ A directive that uses the attribute syntax cannot be applied to the same statement or associated declaration as a directive that uses the pragma syntax. ∙ For any directive that has a paired end directive, both directives must use either the attribute syntax or the pragma syntax. ∙ Neither a stand-alone directive nor a declarative directive may be used in place of a substatement in a selection statement or iteration statement, or in place of the statement that follows a label.

∙ Neither a stand-alone directive nor a declarative directive may be used in place of a substatement in a selection statement, in place of the loop body in an iteration statement, or in place of the statement that follows a label.

3.1.1 Fixed Source Form Directives
3.1.2 Free Source Form Directives

[next] [prev] [prev-tail] [front] [up]