Directive Format

| OPENMP API Specification: Version 5.1 November 2020

2.1 Directive Format

OpenMP directives for C/C++ may be specified with #pragma directives as follows:

 
#pragma omp directive-name [[,] clause[ [,] clause] ... ] new-line

Where directive-name is the name of the directive and, when specified in the syntax of the directive, any directive-level arguments enclosed in parentheses.

Note – In the following example, depobj(o) is the directive-name:

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

Each #pragma directive starts with #pragma omp. The remainder of the directive follows the conventions of the C and C++ standards for compiler directives. In particular, white space can be used before and after the #, and sometimes white space must be used to separate the words in a directive. Preprocessing tokens following #pragma omp are subject to macro replacement.

Some OpenMP directives may be composed of consecutive #pragma directives if specified in their syntax.

In C++11 and higher, all OpenMP directives may be specified with C++ attribute specifiers as follows:

 
[[ omp :: directive( directive-name[[,] clause[[,] clause]... ]  ) ]]

 
[[ using omp : directive( directive-name[[,] clause[[,] clause]... ]  ) ]]

The above two forms are interchangeable for any OpenMP directive. Some OpenMP directives may be composed of consecutive attribute specifiers if specified in their syntax. Any two consecutive attribute specifiers may be reordered or expressed as a single attribute specifier, as permitted by the base language, without changing the behavior of the OpenMP directive.

Some directives may have additional forms that use the attribute syntax.

Multiple attributes on the same statement are allowed. A directive that uses the attribute syntax cannot be applied to the same statement as a directive that uses the pragma syntax. For any directive that has a paired end directive, including those with a begin and end pair, both directives must use either the attribute syntax or the pragma syntax. Attribute directives that apply to the same statement are unordered. An ordering can be imposed with the sequence attribute, which is specified as follows:

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

where directive-attr is any attribute in the omp namespace, optionally specified with a omp:: namespace qualifier, which may be another sequence attribute.

The application of multiple attributes in a sequence attribute is ordered as if each directive had been written as a #pragma directive on subsequent lines.

Note – This is an example of the expected transformation:

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

Directives are case-sensitive.

Each of the expressions used in the OpenMP syntax inside of the clauses must be a valid assignment-expression of the base language unless otherwise specified.

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

OpenMP directives for Fortran are specified as follows:

 
sentinel directive-name [clause[ [,] clause]...]

All OpenMP compiler directives must begin with a directive sentinel. The format of a sentinel differs between fixed form and free form source files, as described in Section 2.1.1 and Section 2.1.2.

Directives are case insensitive. Directives cannot be embedded within continued statements, and statements cannot be embedded within directives.

Each of the expressions used in the OpenMP syntax inside of the clauses must be a valid expression of the base language unless otherwise specified.

In order to simplify the presentation, free form is used for the syntax of OpenMP directives for Fortran in the remainder of this document, except as noted.

A directive may be categorized as one of the following: a metadirective, a declarative directive, an executable directive, an informational directive, or a utility directive.

Only one directive-name can be specified per directive (note that this includes combined directives, see Section 2.16). The order in which clauses appear on directives is not significant. Clauses on directives may be repeated as needed, subject to the restrictions listed in the description of each clause or the directives on which they can appear.

Some clauses accept a list, an extended-list, or a locator-list. A list consists of a comma-separated collection of one or more list items. An extended-list consists of a comma-separated collection of one or more extended list items. A locator-list consists of a comma-separated collection of one or more locator list items.

A list item is a variable or an array section. An extended list item is a list item or a function name. A locator list item is any lvalue expression including variables, an array section, or a reserved locator.

A list item is a variable that is not coindexed, an array section that is not coindexed, a named constant, an associate name that may appear in a variable definition context, or a common block name (enclosed in slashes). An extended list item is a list item or a procedure name. A locator list item is a list item, or a reserved locator.

A named constant as a list item can appear only in clauses where it is explicitly allowed.

When a named common block appears in a list, it has the same meaning and restrictions as if every explicit member of the common block appeared in the list. An explicit member of a common block is a variable that is named in a COMMON statement that specifies the common block name and is declared in the same scoping unit in which the clause appears. Named common blocks do not include the blank common block.

Although variables in common blocks can be accessed by use association or host association, common block names cannot. As a result, a common block name specified in a data-sharing attribute, a data copying, or a data-mapping attribute clause must be declared to be a common block in the same scoping unit in which the clause appears.

If a list item that appears in a directive or clause is an optional dummy argument that is not present, the directive or clause for that list item is ignored.

If the variable referenced inside a construct is an optional dummy argument that is not present, any explicitly determined, implicitly determined, or predetermined data-sharing and data-mapping attribute rules for that variable are ignored. Otherwise, if the variable is an optional dummy argument that is present, it is present inside the construct.

For all base languages, a list item, an extended list item, or a locator list item is subject to the restrictions specified in Section 2.1.5 and in each of the sections that describe clauses and directives for which the list, the extended-list, or the locator-list appears.

Some clauses and directives accept the use of reserved locators as special identifiers that represent system storage not necessarily bound to any base language storage item. Reserved locators may only appear in clauses and directives where they are explicitly allowed and may not otherwise be referenced in the program. The list of reserved locators is:

 
omp_all_memory

The reserved locator omp_all_memory is a reserved identifier that denotes a list item treated as having storage that corresponds to the storage of all other objects in memory.

Some directives have an associated structured block or a structured block sequence.

A structured block sequence that consists of more than one statement may appear only for executable directives that explicitly allow it. The corresponding compound statement obtained by enclosing the sequence in { and } must be a structured block and the structured block sequence then should be considered to be a structured block with all of its restrictions.

A structured block:

may contain infinite loops where the point of exit is never reached;
may halt due to an IEEE exception;

∙ may contain calls to exit(), _Exit(), quick_exit(), abort() or functions with a _Noreturn specifier (in C) or a noreturn attribute (in C/C++); ∙ may be an expression statement, iteration statement, selection statement, or try block, provided that the corresponding compound statement obtained by enclosing it in { and } would be a structured block; and

∙ may contain STOP or ERROR STOP statements.

Restrictions Restrictions to structured blocks are as follows:

Entry to a structured block must not be the result of a branch.
The point of exit cannot be a branch out of the structured block.

∙ The point of entry to a structured block must not be a call to setjmp. ∙ longjmp must not violate the entry/exit criteria.

∙ throw must not violate the entry/exit criteria. ∙ co_await, co_yield and co_return must not violate the entry/exit criteria.

When a BLOCK construct appears in a structured block, that BLOCK construct must not contain any ASYNCHRONOUS or VOLATILE statements, nor any specification statements that include the ASYNCHRONOUS or VOLATILE attributes.

Restrictions on explicit OpenMP regions (that arise from executable directives) are as follows:

If more than one image is executing the program, any image control statement, ERROR STOP statement, FAIL IMAGE statement, collective subroutine call or access to a coindexed object that appears in an explicit OpenMP region will result in unspecified behavior.

  2.1.1  Fixed Source Form Directives
  2.1.2  Free Source Form Directives
  2.1.3  Stand-Alone Directives
  2.1.4  Array Shaping
  2.1.5  Array Sections
  2.1.6  Iterators

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