HOME
| OPENMP API Specification: Version 5.1 November 2020

2.7  teams Construct

Summary The teams construct creates a league of initial teams and the initial thread in each team executes the region.

Syntax

SVG-Viewer needed.

The syntax of the teams construct is as follows:  

 
#pragma omp teams [clause[ [,] clause] ... ] new-line 
    structured-block  

where clause is one of the following:  

 
num_teams([lower-bound:]upper-bound) 
thread_limit(integer-expression) 
default(data-sharing-attribute) 
private(list) 
firstprivate(list) 
shared(list) 
reduction([default ,] reduction-identifier : list) 
allocate([allocator :] list)  

and where lower-bound and upper-bound are scalar integer expressions.

SVG-Viewer needed.

SVG-Viewer needed.

The syntax of the teams construct is as follows:  

 
!$omp teams [clause[ [,] clause] ... ] 
    loosely-structured-block 
!$omp end teams  

or  

 
!$omp teams [clause[ [,] clause] ... ] 
    strictly-structured-block 
[!$omp end teams]  

where clause is one of the following:  

 
num_teams([lower-bound:]upper-bound) 
thread_limit(scalar-integer-expression) 
default(data-sharing-attribute) 
private(list) 
firstprivate(list) 
shared(list) 
reduction([default ,] reduction-identifier : list) 
allocate([allocator :] list)  

and where lower-bound and upper-bound are scalar integer expressions.

SVG-Viewer needed.

Binding The binding thread set for a teams region is the encountering thread.

Description When a thread encounters a teams construct, a league of teams is created. Each team is an initial team, and the initial thread in each team executes the teams region.

If the num_teams clause is present, lower-bound is the specified lower bound and upper-bound is the specified upper bound on the number of teams requested. If a lower bound is not specified, the lower bound is set to the specified upper bound. The number of teams created is implementation defined, but it will be greater than or equal to the lower bound and less than or equal to the upper bound.

If the num_teams clause is not specified and the value of the nteams-var ICV is greater than zero, the number of teams created is less or equal to the value of the nteams-var ICV. Otherwise, the number of teams created is implementation defined, but it will be greater than or equal to 1.

A thread may obtain the number of teams created by the construct with a call to the omp_get_num_teams routine.

If a thread_limit clause is not present on the teams construct, but the construct is closely nested inside a target construct on which the thread_limit clause is specified, the behavior is as if that thread_limit clause is also specified for the teams construct.

As described in Section 2.4.4.1, the teams construct limits the number of threads that may participate in a contention group initiated by each team by setting the value of the thread-limit-var ICV for the initial task to an implementation defined value greater than zero. If the thread_limit clause is specified, the number of threads will be less than or equal to the value specified in the clause. Otherwise, if the teams-thread-limit-var ICV is greater than zero, the number of threads will be less than or equal to that value.

On a combined or composite construct that includes target and teams constructs, the expressions in num_teams and thread_limit clauses are evaluated on the host device on entry to the target construct.

Once the teams are created, the number of initial teams remains constant for the duration of the teams region.

Within a teams region, initial team numbers uniquely identify each initial team. Initial team numbers are consecutive whole numbers ranging from zero to one less than the number of initial teams. A thread may obtain its own initial team number by a call to the omp_get_team_num library routine.

The place list, given by the place-partition-var ICV of the encountering thread, is split into subpartitions in an implementation-defined manner, and each team is assigned to a subpartition by setting the place-partition-var of its initial thread to the subpartition.

The teams construct sets the default-device-var ICV for each initial thread to an implementation-defined value.

After the teams have completed execution of the teams region, the encountering task resumes execution of the enclosing task region.

Execution Model Events The teams-begin event occurs in a thread that encounters a teams construct before any initial task is created for the corresponding teams region.

Upon creation of each initial task, an initial-task-begin event occurs in the thread that executes the initial task after the initial task is fully initialized but before the thread begins to execute the structured block of the teams construct.

If the teams region creates a native thread, a native-thread-begin event occurs as the first event in the context of the new thread prior to the initial-task-begin event.

When a thread finishes an initial task, an initial-task-end event occurs in the thread.

The teams-end event occurs in the thread that encounters the teams construct after the thread executes its initial-task-end event but before it resumes execution of the encountering task.

If a native thread is destroyed at the end of a teams region, a native-thread-end event occurs in the thread as the last event prior to destruction of the thread.

Tool Callbacks A thread dispatches a registered ompt_callback_parallel_begin callback for each occurrence of a teams-begin event in that thread. The callback occurs in the task that encounters the teams construct. This callback has the type signature ompt_callback_parallel_begin_t. In the dispatched callback, (flags & ompt_parallel_league) evaluates to true.

A thread dispatches a registered ompt_callback_implicit_task callback with ompt_scope_begin as its endpoint argument for each occurrence of an initial-task-begin in that thread. Similarly, a thread dispatches a registered ompt_callback_implicit_task callback with ompt_scope_end as its endpoint argument for each occurrence of an initial-task-end event in that thread. The callbacks occur in the context of the initial task and have type signature ompt_callback_implicit_task_t. In the dispatched callback, (flags & ompt_task_initial) evaluates to true.

A thread dispatches a registered ompt_callback_parallel_end callback for each occurrence of a teams-end event in that thread. The callback occurs in the task that encounters the teams construct. This callback has the type signature ompt_callback_parallel_end_t.

A thread dispatches a registered ompt_callback_thread_begin callback for the native-thread-begin event in that thread. The callback occurs in the context of the thread. The callback has type signature ompt_callback_thread_begin_t.

A thread dispatches a registered ompt_callback_thread_end callback for the native-thread-end event in that thread. The callback occurs in the context of the thread. The callback has type signature ompt_callback_thread_end_t.

Restrictions Restrictions to the teams construct are as follows:

Cross References