HOME
| OPENMP API Specification: Version 5.0 November 2018

2.4  requires Directive

SummaryThe requires directive specifies the features that an implementation must provide in order for the code to compile and to execute correctly. The requires directive is a declarative directive.

Syntax

SVG-Viewer needed.

The syntax of the requires directive is as follows:  

 
  #pragma omp requires clause[ [ [,] clause] ... ] new-line  

SVG-Viewer needed.

SVG-Viewer needed.

The syntax of the requires directive is as follows:  

 
!$omp requires clause[ [ [,] clause] ... ]  

SVG-Viewer needed.

Where clause is either one of the requirement clauses listed below or a clause of the form ext_implementation-defined-requirement for an implementation defined requirement clause.  

 
reverse_offload 
unified_address 
unified_shared_memory 
atomic_default_mem_order(seq_cst | acq_rel | relaxed) 
dynamic_allocators  

Description The requires directive specifies features that an implementation must support for correct execution. The behavior that a requirement clause specifies may override the normal behavior specified elsewhere in this document. Whether an implementation supports the feature that a given requirement clause specifies is implementation defined.

The requires directive specifies requirements for the execution of all code in the current compilation unit.

SVG-Viewer needed.

Note – Use of this directive makes your code less portable. Users should be aware that not all devices or implementations support all requirements.

SVG-Viewer needed.

When the reverse_offload clause appears on a requires directive, the implementation guarantees that a target region, for which the target construct specifies a device clause in which the ancestor modifier appears, can execute on the parent device of an enclosing target region.

When the unified_address clause appears on a requires directive, the implementation guarantees that all devices accessible through OpenMP API routines and directives use a unified address space. In this address space, a pointer will always refer to the same location in memory from all devices accessible through OpenMP. The pointers returned by omp_target_alloc and accessed through use_device_ptr are guaranteed to be pointer values that can support pointer arithmetic while still being native device pointers. The is_device_ptr clause is not necessary for device pointers to be translated in target regions, and pointers found not present are not set to null but keep their original value. Memory local to a specific execution context may be exempt from this requirement, following the restrictions of locality to a given execution context, thread, or contention group. Target devices may still have discrete memories and dereferencing a device pointer on the host device or host pointer on a target device remains unspecified behavior.

The unified_shared_memory clause implies the unified_address requirement, inheriting all of its behaviors. Additionally, memory in the device data environment of any device visible to OpenMP, including but not limited to the host, is considered part of the device data environment of all devices accessible through OpenMP except as noted below. Every device address allocated through OpenMP device memory routines is a valid host pointer. Memory local to an execution context as defined in unified_address above may remain part of distinct device data environments as long as the execution context is local to the device containing that environment.

The unified_shared_memory clause makes the map clause optional on target constructs and the declare target directive optional for static lifetime variables accessed inside declare target functions. Scalar variables are still firstprivate by default when referenced inside target constructs. Values stored into memory by one device may not be visible to another device until those two devices synchronize with each other or both devices synchronize with the host.

The atomic_default_mem_order clause specifies the default memory ordering behavior for atomic constructs that must be provided by an implementation. If the default memory ordering is specified as seq_cst, all atomic constructs on which memory-order-clause is not specified behave as if the seq_cst clause appears. If the default memory ordering is specified as relaxed, all atomic constructs on which memory-order-clause is not specified behave as if the relaxed clause appears.

If the default memory ordering is specified as acq_rel, atomic constructs on which memory-order-clause is not specified behave as if the release clause appears if the atomic write or atomic update operation is specified, as if the acquire clause appears if the atomic read operation is specified, and as if the acq_rel clause appears if the atomic captured update operation is specified.

The dynamic_allocators clause removes certain restrictions on the use of memory allocators in target regions. It makes the uses_allocators clause optional on target constructs for the purpose of using allocators in the corresponding target regions. It allows calls to the omp_init_allocator and omp_destroy_allocator API routines in target regions. Finally, it allows default allocators to be used by allocate directives, allocate clauses, and omp_alloc API routines in target regions.

Implementers are allowed to include additional implementation defined requirement clauses. All implementation defined requirements should begin with ext_. Requirement names that do not start with ext_ are reserved.

RestrictionsThe restrictions for the requires directive are as follows: