The #pragma omp for directive identifies an iterative work-sharing construct that specifies a region in which the iterations of the associated loop should be executed in parallel. The iterations of the for loop are distributed across threads that already exist. The #pragma omp for directive has the following syntax:

#pragma omp for [clause[ clause]
... ] new-linefor-loop

clause is one of the following:

For information on the private, firstprivate, lastprivate, and reduction clauses, see “Data Scope Attribute Clauses”.

The #pragma omp for directive places restrictions on the structure of the corresponding for loop, which must have the following canonical shape:

for (init-expr;
var logical-op b; incr-expr)

var = lb
integer-type var = lb

++var
var++
--var
var--
var += incr
var -= incr
var = var + incr
var = incr + var
var = var - incr

<
<=
>
>=

The schedule clause specifies how iterations of the for loop are divided among threads of the team. The value of chunk_size, if specified, must be a log invariant integer expression with a positive value. Synchronization does not occur during the evaluation of this expression, therefore, any evaluated side effects produce indeterminate results. The schedule kind can be one of the following:

The default schedule is implementation-dependent.

An OpenMP-compliant program should not rely on a particular schedule for correct execution. It is possible to have variations in the implementations of the same schedule kind across different compilers.

The ordered clause must be present when ordered directives are contained in the dynamic extent of the for construct.

There is an implicit barrier at the end of a for construct unless a nowait clause is specified.

The following restrictions apply to the #pragma omp for directive:

If there are multiple independent loops within a parallel region, you can use the nowait clause to avoid the implied barrier at the end of the for directive, as follows:

#pragma omp parallel
{
   #pragma omp for nowait
      for (i=1; i<n; i++)
         b[i] = (a[i] + a[i-1]) / 2.0;

The #pragma omp sections directive identifies a non-iterative work-sharing construct that specifies a set of constructs that are to be divided among threads in a team. Each section is executed once by a thread in the team. Each section is preceded by a sections directive, although the sections directive is optional for the first section.

The #pragma omp sections directive has the following syntax:

#pragma omp sections [clause[ clause] ...] new-line
{
[#pragma omp section new-line] structured-block
[#pragma omp section new-linestructured-block
.
.
.]
}

clause is one of the following:

For information on private, firstprivate, lastprivate, and reduction, see “Data Scope Attribute Clauses”.

There is an implicit barrier at the end of a sections construct, unless a nowait is specified.

The following restrictions apply to the sections construct:

The #pragma omp single directive identifies a construct that specifies that the associated structured block is executed by only one thread in the team (not necessarily the master thread). The #pragma omp single directive has the following syntax:

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

clause is one of the following:

For information on the private and firstprivate clauses, see “Data Scope Attribute Clauses”.

There is an implicit barrier after the single construct unless a nowait clause is specified.

The following restrictions apply to the #pragma omp single directive:

In the following example, only one thread (usually the first thread that encounters the single directive) prints the progress message. The user must not make any assumptions as to which thread will execute the single section. All other threads will skip the single section and stop at the barrier at the end of the single construct. If other threads can proceed without waiting for the thread executing the single section, a nowait clause can be specified on the single directive.

#pragma omp parallel
{
  #pragma omp single
    printf("Beginning work1.\n");
  work1();
  #pragma omp single
    printf("Finishing work1.\n");
  #pragma omp single nowait
    printf("Finished work1 and beginning work2.\n");
  work2();
}

The parallel for directive is a shortcut for a parallel region that contains one for directive. It has the following syntax:

#pragma omp parallel for [clause[ clause] ...] new-line for-loop

clause is one of the following:

The following restrictions apply to the parallel for directive:

The #pragma omp parallel sections directive provides a shortcut form for specifying a parallel region containing one sections directive. The parallel sections directive has the following syntax:

#pragma omp parallel sections [clause[ clause] ...] new-line
{
[#pragma omp section new-line] structured-block
[#pragma omp section new-linestructured-block
.
.
.]
}

clause is one of the following:

In the following example, functions xaxis, yaxis, and zaxis can be executed concurrently. The first section directive is optional. Note that all section directives must appear in the lexical extent of the parallel sections construct.

#pragma omp parallel sections
{
   #pragma omp section
     xaxis();
   #pragma omp section
     yaxis();
   #pragma omp section
     zaxis();
}

The #pragma omp master directive identifies a construct that specifies a structured block that is executed by the master thread of the team. It has the following syntax:

#pragma omp master new-linestructured-block

Other threads in the team do not execute the associated statement. There is no implied barrier either on entry to or exit from the master section.

The #pragma omp critical directive identifies a construct that restricts execution of the associated structured block to one thread at a time. It has the following syntax:

#pragma omp critical [(name)] new-linestructured-block

An optional name that has external linkage may be used to identify the critical region.

A thread waits at the beginning of a criical region until no other thread is executing a critical region with the same name. All unnamed #pragma omp critical directives map to the same unspecified name.

The following example includes several #pragma omp critical directives. It illustrates a queuing model in which a task is dequeued and worked on. To guard against multiple threads dequeuing the same task, the dequeuing operation must be in a #pragma omp critical section. Because the two queues in this example are independent, they are protected by #pragma omp critical directives with different names, xaxis and yaxis.

#pragma omp parallel shared(x, y) private(x_next, y_next)
{
   #pragma omp critical ( xaxis )
     x_next = dequeue(x);
   work(x_next);
   #pragma omp critical ( yaxis )
     y_next = dequeue(y);
   work(y_next);
}

The #pragma omp barrier directive synchronizes all the threads in a team, each thread waiting until all other threads have reached this point. After all threads have been synchronized, they begin executing the statements after the barrier directive in parallel. The barrier directive has the following syntax:

#pragma omp barrier new-line

The #pragma omp atomic directive ensures that a specific memory location is updated atomically. The atomic directive has the following syntax:

#pragma omp atomic new-lineexpression-stmt

The expression-stmt must have one of the following forms:

x binop = expr
x++
++x
x--
--x

Where:

Although a conforming implementation can replace all #pragma omp atomic directives with critical directives that have the same unique name, the #pragma omp atomic directive permits better optimization. Often hardware instructions are available that can perform the atomic update with the least overhead.

Only the load and store of the object designated by x are atomic. To avoid race conditions, all updates of the location in parallel should be protected with the atomic directive, unless they are known to be free of race conditions.

The following restrictions apply to the #pragma omp atomic directive:

Examples:

extern float a[], *p = a, b;
/* Protect against races among multiple updates.*/
#pragma omp atomic
a[index[i] += b;
/* Protect against races with updates through a.*/
#pragma omp atomic
p[i] -= 1.0f;
extern union {int n; float x;} u;
/* ERROR - References through incompatible types.*/
#pragma omp atomic
u.n++;
#pragma omp atomic
u.x -= 1.0f;

The #pragma omp flush directive, explicit or implied, identifies precise synchronization points at which the implementation is required to provide a consistent view of certain objects in memory. This means that previous evaluations of expressions that reference those objects are complete and subsequent evaluations have not yet begun.

The flush directive has the following syntax:

#pragma omp flush [(list)] new-line

If no list is specified, all shared objects except inaccessible objects with automatic storage duration are synchronized. A flush directive without a list is implied for the following directives:

The directive is not implied if a nowait clause is present.

A reference that accesses the value of an object with a volatile-qualified type behaves as if there were a flush directive specifying that object at the previous sequence point. A reference that modifies the value of an object with a volatile-qualified type behaves as if there were a flush directive specifying that object at the subsequent sequence point.

The following restriction applies to the flush directive:

The following example uses the flush directive for point-to-point synchronization of specific objects between pairs of threads:

#pragma omp parallel private(iam,neighbor) shared(work,sync)
{

  iam = omp_get_thread_num();
  sync[iam] = 0;
  #pragma omp barrier

  /*Do computation into my portion of work array */
  work[iam] = ...;

  /*  Announce that I am done with my work
   *  The first flush ensures that my work is made visible before sync.
   *  The second flush ensures that sync is made visible.
   */
  #pragma omp flush(work)
  sync[iam] = 1;
  #pragma omp flush(sync)

  /*Wait for neighbor*/
  neighbor = (iam>0 ? iam : omp_get_num_threads()) - 1;
  while (sync[neighbor]==0) {
    #pragma omp flush(sync)
  }

  /*Read neighbor's values of work array */
  ... = work[neighbor];
}

The following example distinguishes the shared objects affected by a flush directive with no list from the shared objects that are not affected:

int x, *p = &x;

void f1(int *q)
{
  *q = 1;
  #pragma omp flush
  // x, p, and *q are flushed
  //   because they are shared and accessible
}

void f2(int *q)
{
  *q = 2;
  #pragma omp barrier
  // a barrier implies a flush
  // x, p, and *q are flushed
  //   because they are shared and accessible
}

int g(int n)
{
  int i = 1, j, sum = 0;
  *p = 1;
  #pragma omp parallel reduction(+: sum)
  {
    f1(&j);
    // i and n were not flushed
    //   because they were not accessible in f1
    // j was flushed because it was accessible
    sum += j;
    f2(&j);
    // i and n were not flushed
    //   because they were not accessible in f2
    // j was flushed because it was accessible
    sum += i + j + *p + n;
  }
  return sum;
}

A #pragma omp ordered directive must be within the dynamic extent of a for or parallel for construct that has an ordered clause. The structured-block following an ordered directive is executed in the same order as iterations in a sequential loop. It has the following syntax:

#pragma omp ordered new-linestructured-block

The following restrictions apply to an ordered directive:

Ordered sections are useful for sequentially ordering the output from work that is done in parallel. The following program prints out the indexes in sequential order:

#pragma omp for ordered schedule(dynamic)
  for (i=lb; i<ub; i+=st)
    work(i);

void work(int k)
{
  #pragma omp ordered
    printf(" %d", k);
}

The #pragma omp threadprivate directive makes named common blocks private to a thread but global within the thread. In other words, each thread executing a threadprivate directive receives its own private copy of the named common blocks, which are then available to it in any routine within the scope of an application.

The threadprivate directive has the following syntax:

#pragma omp threadprivate(list) new-line

A thread must not reference another thread's copy of a threadprivate object. During serial regions and master regions of the program, references will be to the master thread's copy of the object.

On entry to the first parallel region, data in the threadprivate common blocks should be assumed to be undefined unless a copyin clause is specified on the parallel directive. When a common block that is initialized using data statements appears in a threadprivate directive, each thread's copy is initialized once prior to its first use. For subsequent parallel regions, the data in the threadprivate common blocks are guaranteed to persist only if the dynamic threads mechanism has been disabled and if the number of threads are the same for all the parallel regions. For more information on dynamic threads, see the omp_set_dynamic(3) library function and the OMP_DYNAMIC environment variable on the pe_environ(5) man page.

The following restrictions apply to the threadprivate directive:

Several directives accept clauses that allow a user to control the scope attributes of variables for the duration of the construct. Not all of the clauses in this section are allowed on all directives, but the clauses that are valid on a particular directive are included with the description of the directive. Usually, if no data scope clauses are specified for a directive, the default scope for variables affected by the directive is share.

The following sections describe the data scope attribute clauses:

private(list)

int i, j;
i = 1;
j = 2;
#pragma omp parallel private(i) firstprivate(j)
{
  i = 3;
  j = j + 2;
}
printf("%d %d\n", i, j);

firstprivate(list)

lastprivate(list)

#pragma omp parallel
{
   #pragma omp for lastprivate(i)
     for (i=0; i<n; i++)
       a[i] = b[i] + b[i+1];
}
a[i]=b[i];

shared(list)

default(shared | none)

#pragma omp parallel for default(shared) firstprivate(i) private(x)/private(r) lastprivate(i)

int x, y, z[1000];
#pragma omp threadprivate(x)

void fun(int a) {
  const int c = 1;
  int i = 0;

  #pragma omp parallel default(none) private(a) shared(z)
  {
     int j = omp_get_num_thread();
                // O.K.  - j is declared within parallel region
     a = z[j];   // O.K.  - a is listed in private clause
                //       - z is listed in shared clause
     x = c;     // O.K.  - x is threadprivate
                 //       - c has const-qualified type
     z[i] = y;   // Error - cannot reference i or y here

     #pragma omp for firstprivate(y)
     for (i=0; i<10 ; i++) {
         z[i] = y;  // O.K. - i is the loop control variable
                    //      - y is listed in firstprivate clause
     }
     z[i] = y;   // Error - cannot reference i or y here
  }
}

reduction(op:list)

x = x opexpr
x <binop> = expr
x = expr op x (except for subtration)
x++
++x
x--
--x

#pragma omp parallel for reduction(+: a, y) reduction(||: am) for (i=0; i<n; i++) {
   a += b[i];
   y = sun(y, c[i];
   am = am || b[i] == c[i];
}

#pragma omp parallel private(y)
{ /* ERROR - private variable y cannot be specified in a reduction clause */
   #pragma omp for reduction(+: y)
   for (i=0; i<n; i++)
     y += b[i];
}

/* ERROR - variable x cannot be specified in both a shared and a reduction clause */
#pragma omp parallel for shared(x) reduction(+: x)

copyin(list)