Developer Guide and Reference

ID 767251
Date 10/31/2024
Public
Document Table of Contents

METADIRECTIVE

OpenMP* Fortran Compiler Directive: Specifies variant OpenMP* directives, one of which may conditionally replace the metadirective based on the OpenMP context enclosing the metadirective.

Syntax

!$OMP METADIRECTIVE [clause [[,] clause]...]

-or-

!$OMP BEGIN METADIRECTIVE [clause [[,] clause]...]

   statement(s)

!$OMP END METADIRECTIVE

clause

Is one of the following:

  • DEFAULT ( [ directive-variant ] )

    This clause has been deprecated and renamed OTHERWISE.

  • OTHERWISE ( [ directive-variant ] )

    Identifies a default directive-variant if the context does not match one of the WHEN clauses. Only one OTHERWISE clause can be specified. If it appears, it must be the last clause specified. If it does not appear, it is as if OTHERWISE (NOTHING) appears.

  • WHEN ( context-selector-spec :[ directive-variant ] )

    Specifies a directive-variant to replace the METADIRECTIVE when the OpenMP context matches the context-selector specified. Expressions in the context-selector of a WHEN clause are evaluated if no prior WHEN clause in the directive specifies a compatible or matching OpenMP context. The number of times an expression can be evaluated is implementation defined.

directive-variant

Is an OpenMP directive (with no sentinel). It is a candidate for replacing the metadirective in which it appears. If directive-variant does not appear, it is as if a NOTHING directive was specified. A directive-variant cannot be a metadirective.

context-selector-spec

Is an OpenMP context-selector. Currently, only USER context selectors whose CONDITION is a logical constant expression are allowed. The context-selector-spec cannot specify properties of a SIMD directive.

statement(s)

Is one or more valid Fortran statements.

A METADIRECTIVE specifies one or more candidate OpenMP directives (directive-variant s) that may conditionally replace the METADIRECTIVE. Selection of a replacement candidate depends on the OpenMP context that encloses the METADIRECTIVE.

The order of clauses is significant. Replacement candidates are ordered according to these rules, in decreasing precedence:

  • A directive-variant candidate has higher precedence than another candidate if the score of the context-selector of its corresponding WHEN clause is higher.

  • Explicitly specified candidates have precedence over implicitly specified candidates.

  • A directive-variant candidate that appears in a WHEN clause specified lexically before another in a METADIRECTIVE has higher precedence.

The first replacement candidate in the ordered list of candidates whose corresponding WHEN clause specifies a compatible context-selector replaces the METADIRECTIVE. See Score and Match OpenMP Context Selectors.

Replacement of the METADIRECTIVE with the selected directive-variant must result in a conforming OpenMP program.

Example

In the program below, _OFFLOADING is a preprocessor macro.

  PROGRAM offloading_success
  USE omp_lib
  IMPLICIT NONE
  INTEGER :: errors
  LOGICAL :: is_host

  is_host = .FALSE.

  !$omp BEGIN METADIRECTIVE WHEN(USER={CONDITION(_OFFLOADING)}: PARALLEL DO SIMD) &
               WHEN(USER={CONDITION(_OFFLOADING)}: TARGET MAP (FROM: is_host)  

     isHost = omp_is_initial_device ()

  !$omp END METADIRECTIVE

  ! check if target region executed on the device
  IF (is_host) THEN
     errors = 1
     PRINT *, "Failed - target region executed on the host"
  ELSE
     errors = 0
     PRINT *, "Passed"
  END IF

  IF( errors .NE. 0 ) STOP 1

  END PROGRAM offloading_success

If the above program is preprocessed with _OFFLOADING defined to be .TRUE., the METADIRECTIVE construct will be replaced with the following:

  !$omp TARGET MAP (FROM:is_host)
  is_host = omp_is_initial_device ()
  !$omp END TARGET

The code following the METADIRECTIVE determines if the METADIRECTIVE resulted in a TARGET region. If so, it tests to determine whether the TARGET region successfully offloaded to the device.