threadprivate Directive

| OPENMP API Specification: Version 5.0 November 2018

2.19.2 threadprivate Directive

SummaryThe threadprivate directive specifies that variables are replicated, with each thread having its own copy. The threadprivate directive is a declarative directive.

Syntax

The syntax of the threadprivate directive is as follows:

 
#pragma omp threadprivate(list) new-line

where list is a comma-separated list of file-scope, namespace-scope, or static block-scope variables that do not have incomplete types.

The syntax of the threadprivate directive is as follows:

 
!$omp threadprivate(list)

where list is a comma-separated list of named variables and named common blocks. Common block names must appear between slashes.

DescriptionEach copy of a threadprivate variable is initialized once, in the manner specified by the program, but at an unspecified point in the program prior to the first reference to that copy. The storage of all copies of a threadprivate variable is freed according to how static variables are handled in the base language, but at an unspecified point in the program.

A program in which a thread references another thread’s copy of a threadprivate variable is non-conforming.

The content of a threadprivate variable can change across a task scheduling point if the executing thread switches to another task that modifies the variable. For more details on task scheduling, see Section 1.3 on page 52 and Section 2.10 on page 384.

In parallel regions, references by the master thread will be to the copy of the variable in the thread that encountered the parallel region.

During a sequential part references will be to the initial thread’s copy of the variable. The values of data in the initial thread’s copy of a threadprivate variable are guaranteed to persist between any two consecutive references to the variable in the program provided that no teams construct that is not nested inside of a target construct is encountered between the references and that the initial thread is not nested inside of a teams region. For initial threads nested inside of a teams region, the values of data in the copies of a threadprivate variable of those initial threads are guaranteed to persist between any two consecutive references to the variable inside of that teams region.

The values of data in the threadprivate variables of threads that are not initial threads are guaranteed to persist between two consecutive active parallel regions only if all of the following conditions hold:

Neither parallel region is nested inside another explicit parallel region;
The number of threads used to execute both parallel regions is the same;
The thread affinity policies used to execute both parallel regions are the same;
The value of the dyn-var internal control variable in the enclosing task region is false at entry to both parallel regions; and
No teams construct that is not nested inside of a target construct is encountered between both parallel regions.
Neither the omp_pause_resource nor omp_pause_resource_all routine is called.

If these conditions all hold, and if a threadprivate variable is referenced in both regions, then threads with the same thread number in their respective regions will reference the same copy of that variable.

If the above conditions hold, the storage duration, lifetime, and value of a thread’s copy of a threadprivate variable that does not appear in any copyin clause on the second region will be retained. Otherwise, the storage duration, lifetime, and value of a thread’s copy of the variable in the second region is unspecified.

If the above conditions hold, the definition, association, or allocation status of a thread’s copy of a threadprivate variable or a variable in a threadprivate common block that is not affected by any copyin clause that appears on the second region (a variable is affected by a copyin clause if the variable appears in the copyin clause or it is in a common block that appears in the copyin clause) will be retained. Otherwise, the definition and association status of a thread’s copy of the variable in the second region are undefined, and the allocation status of an allocatable variable will be implementation defined.

If a threadprivate variable or a variable in a threadprivate common block is not affected by any copyin clause that appears on the first parallel region in which it is referenced, the thread’s copy of the variable inherits the declared type parameter and the default parameter values from the original variable. The variable or any subobject of the variable is initially defined or undefined according to the following rules:

If it has the ALLOCATABLE attribute, each copy created will have an initial allocation status of unallocated;
If it has the POINTER attribute:
- If it has an initial association status of disassociated, either through explicit initialization or default initialization, each copy created will have an association status of disassociated;
- Otherwise, each copy created will have an association status of undefined.
If it does not have either the POINTER or the ALLOCATABLE attribute:
- If it is initially defined, either through explicit initialization or default initialization, each copy created is so defined;
- Otherwise, each copy created is undefined.

The address of a threadprivate variable is not an address constant.

The order in which any constructors for different threadprivate variables of class type are called is unspecified. The order in which any destructors for different threadprivate variables of class type are called is unspecified.

RestrictionsThe restrictions to the threadprivate directive are as follows:

A threadprivate variable must not appear in any clause except the copyin, copyprivate, schedule, num_threads, thread_limit, and if clauses.
A program in which an untied task accesses threadprivate storage is non-conforming.

∙ If the value of a variable referenced in an explicit initializer of a threadprivate variable is modified prior to the first reference to any instance of the threadprivate variable, then the behavior is unspecified. ∙ A variable that is part of another variable (as an array or structure element) cannot appear in a threadprivate clause unless it is a static data member of a C++ class. ∙ A threadprivate directive for file-scope variables must appear outside any definition or declaration, and must lexically precede all references to any of the variables in its list. ∙ A threadprivate directive for namespace-scope variables must appear outside any definition or declaration other than the namespace definition itself, and must lexically precede all references to any of the variables in its list. ∙ Each variable in the list of a threadprivate directive at file, namespace, or class scope must refer to a variable declaration at file, namespace, or class scope that lexically precedes the directive. ∙ A threadprivate directive for static block-scope variables must appear in the scope of the variable and not in a nested scope. The directive must lexically precede all references to any of the variables in its list. ∙ Each variable in the list of a threadprivate directive in block scope must refer to a variable declaration in the same scope that lexically precedes the directive. The variable declaration must use the static storage-class specifier. ∙ If a variable is specified in a threadprivate directive in one translation unit, it must be specified in a threadprivate directive in every translation unit in which it is declared.
∙ A threadprivate directive for static class member variables must appear in the class definition, in the same scope in which the member variables are declared, and must lexically precede all references to any of the variables in its list. ∙ A threadprivate variable must not have an incomplete type or a reference type. ∙ A threadprivate variable with class type must have:
- An accessible, unambiguous default constructor in the case of default initialization without a given initializer;
- An accessible, unambiguous constructor that accepts the given argument in the case of direct initialization; and
- An accessible, unambiguous copy constructor in the case of copy initialization with an explicit initializer.

A variable that is part of another variable (as an array, structure element or type parameter inquiry) cannot appear in a threadprivate clause.
The threadprivate directive must appear in the declaration section of a scoping unit in which the common block or variable is declared.
If a threadprivate directive that specifies a common block name appears in one program unit, then such a directive must also appear in every other program unit that contains a COMMON statement that specifies the same name. It must appear after the last such COMMON statement in the program unit.
If a threadprivate variable or a threadprivate common block is declared with the BIND attribute, the corresponding C entities must also be specified in a threadprivate directive in the C program.
A blank common block cannot appear in a threadprivate directive.
A variable can only appear in a threadprivate directive in the scope in which it is declared. It must not be an element of a common block or appear in an EQUIVALENCE statement.
A variable that appears in a threadprivate directive must be declared in the scope of a module or have the SAVE attribute, either explicitly or implicitly.

Cross References

dyn-var ICV, see Section 2.5 on page 171.
Number of threads used to execute a parallel region, see Section 2.6.1 on page 224.
copyin clause, see Section 2.19.6.1 on page 919.

[next] [prev] [prev-tail] [front] [up]