2.3.6  dispatch Construct

Summary The dispatch construct controls whether variant substitution occurs for a given call.

Syntax

 
#pragma omp dispatch [clause[ [,] clause] ... ] new-line 
    expression-stmt
  

 
expression = target-call ( [expression-list] ); 
target-call ( [expression-list] );
       

 
device(integer-expression) 
depend([depend-modifier,] dependence-type : locator-list) 
nowait 
novariants(scalar-expression) 
nocontext(scalar-expression) 
is_device_ptr(list)
       

 
!$omp dispatch [clause[ [,] clause] ... ] 
    stmt
  

 
expression = target-call ( [arguments] ) 
CALL target-call [ ( [arguments] )]
       

 
device(scalar-integer-expression) 
depend([depend-modifier,] dependence-type : locator-list) 
nowait 
novariants(scalar-logical-expression) 
nocontext(scalar-logical-expression) 
is_device_ptr(list)
       

Binding The binding task set for a dispatch region is the generating task. The dispatch region binds to the region of the generating task.

Description When a novariants clause is present on the dispatch construct, and the novariants clause expression evaluates to true, no function variant will be selected for the target-call even if one would be selected normally. The use of a variable in a novariants clause expression of a dispatch construct causes an implicit reference to the variable in all enclosing constructs.

The novariants clause expression is evaluated in the enclosing context.

When a nocontext clause is present on the dispatch construct, and the nocontext clause expression evaluates to true, the dispatch construct is not added to the construct set of the OpenMP context. The use of a variable in a nocontext clause expression of a dispatch construct causes an implicit reference to the variable in all enclosing constructs.

The nocontext clause expression is evaluated in the enclosing context.

The is_device_ptr clause indicates that its list items are device pointers. For each list item specified in the clause, an is_device_ptr property for that list item is added to the interoperability requirement set. Support for device pointers created outside of OpenMP, specifically outside of any OpenMP mechanism that returns a device pointer, is implementation defined.

If one or more depend clauses are present on the dispatch construct, they are added as depend properties of the interoperability requirement set. If a nowait clause is present on the dispatch construct the nowait property is added to the interoperability requirement set.

This construct creates an explicit task, as if the task construct was used, that surrounds the associated code. Properties added to the interoperability requirement set can be removed by the effect of other directives (see Section 2.15.2) before the task is created. If the interoperability requirement set contains one or more depend properties, the behavior is as if those properties were applied to the task construct as depend clauses. If the interoperability requirement set does not contain the nowait property then the task will also be an included task.

If the device clause is present, the value of the default-device-var ICV of the generated task is set to the value of the expression in the clause.

Restrictions Restrictions to the dispatch construct are as follows:

• At most one novariants clause can appear on a dispatch directive.
• At most one nocontext clause can appear on a dispatch directive.
• At most one nowait clause can appear on a dispatch directive.
• A list item that appears in an is_device_ptr clause must be a valid device pointer for the device data environment.
  ∙ The target-call expression can only be a direct call.

  ∙ target-call must be a procedure name. ∙ target-call must not be a procedure pointer. ∙ A list item that appears in an is_device_ptr clause must be of type C_PTR.

Cross References

• declare variant directive, see Section 2.3.5.
• Interoperability requirement set, see Section 2.15.2.