2.21.5  Reduction Clauses and Directives

The reduction clauses are data-sharing attribute clauses that can be used to perform some forms of recurrence calculations in parallel. Reduction clauses include reduction scoping clauses and reduction participating clauses. Reduction scoping clauses define the region in which a reduction is computed. Reduction participating clauses define the participants in the reduction.

2.21.5.1 Properties Common to All Reduction Clauses

Syntax The syntax of a reduction-identifier is defined as follows:

Description A reduction clause specifies a reduction-identifier and one or more list items.

The reduction-identifier specified in a reduction clause must match a previously declared reduction-identifier of the same name and type for each of the list items. This match is done by means of a name lookup in the base language.

The list items that appear in a reduction clause may include array sections.

If a list item is an array or array section, it will be treated as if a reduction clause would be applied to each separate element of the array section.

If a list item is an array section, the elements of any copy of the array section will be stored contiguously.

Any copies of a list item associated with the reduction are initialized with the initializer value of the reduction-identifier.

Any copies are combined using the combiner associated with the reduction-identifier.

Execution Model Events The reduction-begin event occurs before a task begins to perform loads and stores that belong to the implementation of a reduction and the reduction-end event occurs after the task has completed loads and stores associated with the reduction. If a task participates in multiple reductions, each reduction may be bracketed by its own pair of reduction-begin/reduction-end events or multiple reductions may be bracketed by a single pair of events. The interval defined by a pair of reduction-begin/reduction-end events may not contain a task scheduling point.

Tool Callbacks A thread dispatches a registered ompt_callback_reduction with ompt_sync_region_reduction in its kind argument and ompt_scope_begin as its endpoint argument for each occurrence of a reduction-begin event in that thread. Similarly, a thread dispatches a registered ompt_callback_reduction with ompt_sync_region_reduction in its kind argument and ompt_scope_end as its endpoint argument for each occurrence of a reduction-end event in that thread. These callbacks occur in the context of the task that performs the reduction and has the type signature ompt_callback_sync_region_t.

Restrictions Restrictions common to reduction clauses are as follows:

• Any number of reduction clauses can be specified on the directive, but a list item (or any array element in an array section) can appear only once in reduction clauses for that directive.
• For a reduction-identifier declared in a declare reduction directive, the directive must appear before its use in a reduction clause.
• If a list item is an array section or an array element, its base expression must be a base language identifier.
• If a list item is an array section, it must specify contiguous storage and it cannot be a zero-length array section.
• If a list item is an array section or an array element, accesses to the elements of the array outside the specified array section or array element result in unspecified behavior.
  ∙ A variable that is part of another variable, with the exception of array elements, cannot appear in a reduction clause.

  ∙ A variable that is part of another variable, with the exception of array elements, cannot appear in a reduction clause except if the reduction clause is associated with a construct within a class non-static member function and the variable is an accessible data member of the object for which the non-static member function is invoked.

  ∙ The type of a list item that appears in a reduction clause must be valid for the reduction-identifier. For a max or min reduction in C, the type of the list item must be an allowed arithmetic data type: char, int, float, double, or _Bool, possibly modified with long, short, signed, or unsigned. For a max or min reduction in C++, the type of the list item must be an allowed arithmetic data type: char, wchar_t, int, float, double, or bool, possibly modified with long, short, signed, or unsigned. ∙ A list item that appears in a reduction clause must not be const-qualified. ∙ The reduction-identifier for any list item must be unambiguous and accessible.

  ∙ A variable that is part of another variable, with the exception of array elements, cannot appear in a reduction clause. ∙ A type parameter inquiry cannot appear in a reduction clause. ∙ The type, type parameters and rank of a list item that appears in a reduction clause must be valid for the combiner and initializer. ∙ A list item that appears in a reduction clause must be definable. ∙ A procedure pointer may not appear in a reduction clause. ∙ A pointer with the INTENT(IN) attribute may not appear in the reduction clause. ∙ An original list item with the POINTER attribute or any pointer component of an original list item that is referenced in the combiner must be associated at entry to the construct that contains the reduction clause. Additionally, the list item or the pointer component of the list item must not be deallocated, allocated, or pointer assigned within the region. ∙ An original list item with the ALLOCATABLE attribute or any allocatable component of an original list item that corresponds to a special variable identifier in the combiner or the initializer must be in the allocated state at entry to the construct that contains the reduction clause. Additionally, the list item or the allocatable component of the list item must be neither deallocated nor allocated, explicitly or implicitly, within the region. ∙ If the reduction-identifier is defined in a declare reduction directive, the declare reduction directive must be in the same subprogram, or accessible by host or use association. ∙ If the reduction-identifier is a user-defined operator, the same explicit interface for that operator must be accessible at the location of the declare reduction directive that defines the reduction-identifier. ∙ If the reduction-identifier is defined in a declare reduction directive, any procedure referenced in the initializer clause or combiner expression must be an intrinsic function, or must have an explicit interface where the same explicit interface is accessible as at the declare reduction directive.

Cross References

• ompt_scope_begin and ompt_scope_end, see Section 4.4.4.11.
• ompt_sync_region_reduction, see Section 4.4.4.13.
• ompt_callback_sync_region_t, see Section 4.5.2.13.

2.21.5.2 Reduction Scoping Clauses

Reduction scoping clauses define the region in which a reduction is computed by tasks or SIMD lanes. All properties common to all reduction clauses, which are defined in Section 2.21.5.1, apply to reduction scoping clauses.

The number of copies created for each list item and the time at which those copies are initialized are determined by the particular reduction scoping clause that appears on the construct.

The time at which the original list item contains the result of the reduction is determined by the particular reduction scoping clause.

The location in the OpenMP program at which values are combined and the order in which values are combined are unspecified. Therefore, when comparing sequential and parallel executions, or when comparing one parallel execution to another (even if the number of threads used is the same), bitwise-identical results are not guaranteed to be obtained. Similarly, side effects (such as floating-point exceptions) may not be identical and may not take place at the same location in the OpenMP program.

To avoid data races, concurrent reads or updates of the original list item must be synchronized with the update of the original list item that occurs as a result of the reduction computation.

2.21.5.3 Reduction Participating Clauses

A reduction participating clause specifies a task or a SIMD lane as a participant in a reduction defined by a reduction scoping clause. All properties common to all reduction clauses, which are defined in Section 2.21.5.1, apply to reduction participating clauses.

Accesses to the original list item may be replaced by accesses to copies of the original list item created by a region that corresponds to a construct with a reduction scoping clause.

In any case, the final value of the reduction must be determined as if all tasks or SIMD lanes that participate in the reduction are executed sequentially in some arbitrary order.

2.21.5.4 reduction Clause

Summary The reduction clause specifies a reduction-identifier and one or more list items. For each list item, a private copy is created for each implicit task or SIMD lane and is initialized with the initializer value of the reduction-identifier. After the end of the region, the original list item is updated with the values of the private copies using the combiner associated with the reduction-identifier.

Syntax The syntax of the reduction clause is as follows:  

 
reduction([ reduction-modifier,]reduction-identifier : list)
  

Where reduction-identifier is defined in Section 2.21.5.1, and reduction-modifier is one of the following:  

 
inscan 
task 
default
       

Description The reduction clause is a reduction scoping clause and a reduction participating clause, as described in Section 2.21.5.2 and Section 2.21.5.3.

If reduction-modifier is not present or the defaultreduction-modifier is present, the behavior is as follows. For parallel, scope and worksharing constructs, one or more private copies of each list item are created for each implicit task, as if the private clause had been used. For the simd construct, one or more private copies of each list item are created for each SIMD lane, as if the private clause had been used. For the taskloop construct, private copies are created according to the rules of the reduction scoping clauses. For the teams construct, one or more private copies of each list item are created for the initial task of each team in the league, as if the private clause had been used. For the loop construct, private copies are created and used in the construct according to the description and restrictions in Section 2.21.3. At the end of a region that corresponds to a construct for which the reduction clause was specified, the original list item is updated by combining its original value with the final value of each of the private copies, using the combiner of the specified reduction-identifier.

If the inscanreduction-modifier is present, a scan computation is performed over updates to the list item performed in each logical iteration of the loop associated with the worksharing-loop, worksharing-loop SIMD, or simd construct (see Section 2.11.8). The list items are privatized in the construct according to the description and restrictions in Section 2.21.3. At the end of the region, each original list item is assigned the value described in Section 2.11.8.

If the taskreduction-modifier is present for a parallel, scope, or worksharing construct, then each list item is privatized according to the description and restrictions in Section 2.21.3, and an unspecified number of additional private copies may be created to support task reductions. Any copies associated with the reduction are initialized before they are accessed by the tasks that participate in the reduction, which include all implicit tasks in the corresponding region and all participating explicit tasks that specify an in_reduction clause (see Section 2.21.5.6). After the end of the region, the original list item contains the result of the reduction.

If nowait is not specified for the construct, the reduction computation will be complete at the end of the region that corresponds to the construct; however, if the reduction clause is used on a construct to which nowait is also applied, accesses to the original list item will create a race and, thus, have unspecified effect unless synchronization ensures that they occur after all threads have executed all of their iterations or section constructs, and the reduction computation has completed and stored the computed value of that list item. This can be ensured simply through a barrier synchronization in most cases.

Restrictions Restrictions to the reduction clause are as follows:

• All restrictions common to all reduction clauses, which are listed in Section 2.21.5.1, apply to this clause.
• A list item that appears in a reduction clause of a worksharing construct must be shared in the parallel region to which a corresponding worksharing region binds.
• A list item that appears in a reduction clause of a scope construct must be shared in the parallel region to which a corresponding scope region binds.
• If an array section or an array element appears as a list item in a reduction clause of a worksharing construct, scope construct or loop construct for which the corresponding region binds to a parallel region, all threads that participate in the reduction must specify the same storage location.
• A list item that appears in a reduction clause with the inscan reduction-modifier must appear as a list item in an inclusive or exclusive clause on a scan directive enclosed by the construct.
• A reduction clause without the inscan reduction-modifier may not appear on a construct on which a reduction clause with the inscan reduction-modifier appears.
• A reduction clause with the task reduction-modifier may only appear on a parallel construct, a scope construct, a worksharing construct or a combined or composite construct for which any of the aforementioned constructs is a constituent construct and simd or loop are not constituent constructs.
• A reduction clause with the inscan reduction-modifier may only appear on a worksharing-loop construct, a simd construct or a combined or composite construct for which any of the aforementioned constructs is a constituent construct and distribute is not a constituent construct.
• A list item that appears in a reduction clause of the innermost enclosing worksharing, parallel or scope construct may not be accessed in an explicit task generated by a construct for which an in_reduction clause over the same list item does not appear.
• The task reduction-modifier may not appear in a reduction clause if the nowait clause is specified on the same construct.
  ∙ If a list item in a reduction clause on a worksharing construct, scope construct or loop construct for which the corresponding region binds to a parallel region has a reference type then it must bind to the same object for all threads of the team. ∙ If a list item in a reduction clause on a worksharing construct, scope or loop construct for which the corresponding region binds to a parallel region is an array section or an array element then the base pointer must point to the same variable for all threads of the team. ∙ A variable of class type (or array thereof) that appears in a reduction clause with the inscan reduction-modifier requires an accessible, unambiguous default constructor for the class type. The number of calls to the default constructor while performing the scan computation is unspecified. ∙ A variable of class type (or array thereof) that appears in a reduction clause with the inscan reduction-modifier requires an accessible, unambiguous copy assignment operator for the class type. The number of calls to the copy assignment operator while performing the scan computation is unspecified.

Cross References

• scan directive, see Section 2.11.8.
• List Item Privatization, see Section 2.21.3.
• private clause, see Section 2.21.4.3.

2.21.5.5 task_reduction Clause

Summary The task_reduction clause specifies a reduction among tasks.

Syntax The syntax of the task_reduction clause is as follows:  

 
task_reduction(reduction-identifier : list)
  

where reduction-identifier is defined in Section 2.21.5.1.

Description The task_reduction clause is a reduction scoping clause, as described in 2.21.5.2.

For each list item, the number of copies is unspecified. Any copies associated with the reduction are initialized before they are accessed by the tasks that participate in the reduction. After the end of the region, the original list item contains the result of the reduction.

Restrictions Restrictions to the task_reduction clause are as follows:

• All restrictions common to all reduction clauses, which are listed in Section 2.21.5.1, apply to this clause.

2.21.5.6 in_reduction Clause

Summary The in_reduction clause specifies that a task participates in a reduction.

Syntax The syntax of the in_reduction clause is as follows:  

 
in_reduction(reduction-identifier : list)
  

where reduction-identifier is defined in Section 2.21.5.1.

Description The in_reduction clause is a reduction participating clause, as described in Section 2.21.5.3. For a given list item, the in_reduction clause defines a task to be a participant in a task reduction that is defined by an enclosing region for a matching list item that appears in a task_reduction clause or a reduction clause with task as the reduction-modifier, where either:

1.

The matching list item has the same storage location as the list item in the in_reduction clause; or

2.

A private copy, derived from the matching list item, that is used to perform the task reduction has the same storage location as the list item in the in_reduction clause.

For the task construct, the generated task becomes the participating task. For each list item, a private copy may be created as if the private clause had been used.

For the target construct, the target task becomes the participating task. For each list item, a private copy may be created in the data environment of the target task as if the private clause had been used. This private copy will be implicitly mapped into the device data environment of the target device, if the target device is not the parent device.

At the end of the task region, if a private copy was created its value is combined with a copy created by a reduction scoping clause or with the original list item.

Restrictions Restrictions to the in_reduction clause are as follows:

• All restrictions common to all reduction clauses, which are listed in Section 2.21.5.1, apply to this clause.
• A list item that appears in a task_reduction clause or a reduction clause with task as the reduction-modifier that is specified on a construct that corresponds to a region in which the region of the participating task is closely nested must match each list item. The construct that corresponds to the innermost enclosing region that meets this condition must specify the same reduction-identifier for the matching list item as the in_reduction clause.

2.21.5.7 declare reduction Directive

Summary The following section describes the directive for declaring user-defined reductions. The declare reduction directive declares a reduction-identifier that can be used in a reduction clause. The declare reduction directive is a declarative directive.

Syntax

 
#pragma omp declare reduction(reduction-identifier : typename-list : 
combiner )[initializer-clause] new-line
  

 
#pragma omp declare reduction(reduction-identifier : typename-list : 
combiner) [initializer-clause] new-line
  

 
!$omp declare reduction(reduction-identifier : type-list : combiner) 
[initializer-clause]
  

Description User-defined reductions can be defined using the declare reduction directive. The reduction-identifier and the type identify the declare reduction directive. The reduction-identifier can later be used in a reduction clause that uses variables of the type or types specified in the declare reduction directive. If the directive specifies several types then the behavior is as if a declare reduction directive was specified for each type.

The visibility and accessibility of a user-defined reduction are the same as those of a variable declared at the same location in the program. The enclosing context of the combiner and of the initializer-expr is that of the declare reduction directive. The combiner and the initializer-expr must be correct in the base language as if they were the body of a function defined at the same location in the program.

The combiner specifies how partial results are combined into a single value. The combiner can use the special variable identifiers omp_in and omp_out that are of the type of the variables that this reduction-identifier reduces. Each of the two special variable identifiers denotes one of the values to be combined before executing the combiner. The special omp_out identifier refers to the storage that holds the resulting combined value after executing the combiner.

The number of times that the combiner is executed and the order of these executions for any reduction clause are unspecified.

If the initializer-expr value of a user-defined reduction is not known a priori, the initializer-clause can be used to specify one. The content of the initializer-clause will be used as the initializer for the private copies of reduction list items where the omp_priv identifier will refer to the storage to be initialized. The special identifier omp_orig can also appear in the initializer-clause and it will refer to the storage of the original variable to be reduced.

The number of times that the initializer-expr is evaluated and the order of these evaluations are unspecified.

Restrictions Restrictions to the declare reduction directive are as follows:

• The only variables allowed in the combiner are omp_in and omp_out.
• The only variables allowed in the initializer-clause are omp_priv and omp_orig.
• If the variable omp_orig is modified in the initializer-clause, the behavior is unspecified.
• If execution of the combiner or the initializer-expr results in the execution of an OpenMP construct or an OpenMP API call, then the behavior is unspecified.
• A reduction-identifier may not be re-declared in the current scope for the same type or for a type that is compatible according to the base language rules.
• At most one initializer-clause can be specified.
• The typename-list must not declare new types.
  ∙ A type name in a declare reduction directive cannot be a function type, an array type, a reference type, or a type qualified with const, volatile or restrict.

  ∙ If the initializer-expr is a function name with an argument list, then one of the arguments must be the address of omp_priv.

  ∙ If the initializer-expr is a function name with an argument list, then one of the arguments must be omp_priv or the address of omp_priv.

  ∙ Any selectors in the designator of omp_in and omp_out can only be component selectors. ∙ If the initializer-expr is a subroutine name with an argument list, then one of the arguments must be omp_priv. ∙ Any subroutine or function used in the initializer clause or combiner expression must be an intrinsic function, or must have an accessible interface. ∙ Any user-defined operator, defined assignment or extended operator used in the initializer clause or combiner expression must have an accessible interface. ∙ If any subroutine, function, user-defined operator, defined assignment or extended operator is used in the initializer clause or combiner expression, it must be accessible to the subprogram in which the corresponding reduction clause is specified. ∙ If the length type parameter is specified for a type, it must be a constant, a colon or an *. ∙ If a type with deferred or assumed length parameter is specified in a declare reduction directive, no other declare reduction directive with the same type, the same kind parameters and the same reduction-identifier is allowed in the same scope. ∙ Any subroutine used in the initializer clause or combiner expression must not have any alternate returns appear in the argument list. ∙ If the list item in the corresponding reduction clause is an array or array section, then any procedure used in the initializer clause or combiner expression must either be elemental or have dummy arguments that are scalar. ∙ Any procedure called in the region of initializer-expr or combiner must be pure and may not reference any host-associated variables.

Cross References

• Properties Common to All Reduction Clauses, see Section 2.21.5.1.