DOALL Qualifiers (Fortran Programming Guide)

Fortran Programming Guide

DOALL Qualifiers

All qualifiers on the DOALL directive are optional. The following table summarizes them:

Table 10-4 DOALL Qualifiers


Qualifier	Assertion	Syntax
`PRIVATE`	Do not share variables `u1`, ... between iterations	`DOALL PRIVATE(u1,u2,)`
`SHARED`	Share variables `v1`, `v2`, ... between iterations	`DOALL SHARED(v1,v2,)`
`MAXCPUS`	Use no more than `n` CPUs	`DOALL MAXCPUS(n)`
`READONLY`	The listed variables are not modified in the `DOALL` loop	`DOALL READONLY(v1,v2,)`
`SAVELAST`	Save the last `DO` iteration values of all private variables	`DOALL SAVELAST`
`STOREBACK`	Save the last `DO` iteration values of variables `v1`, ...	`DOALL STOREBACK(v1,v2,)`
`REDUCTION`	Treat the variables `v1`, `v2`, ... as reduction variables.	`DOALL REDUCTION(v1,v2,)`
`SCHEDTYPE`	Set the scheduling type to `t`.	`DOALL SCHEDTYPE(t)`

`PRIVATE(varlist)`

The PRIVATE(varlist)qualifier specifies that all scalars and arrays in the list varlist are private for the DOALL loop. Both arrays and scalars can be specified as private. In the case of an array, each thread of the DOALL loop gets a copy of the entire array. All other scalars and arrays referenced in the DOALL loop, but not contained in the private list, conform to their appropriate default scoping rules.

Example: Specify a private array:

C$PAR DOALL PRIVATE(a)
      do i = 1, n
        a(1) = b(i)
        do j = 2, n
          a(j) = a(j-1) + b(j) * c(j)
        end do
        x(i) = f(a)
      end do

In the preceding example, the array a is specified as private to the i loop.

`SHARED(varlist)`

The SHARED(varlist) qualifier specifies that all scalars and arrays in the list varlist are shared for the DOALL loop. Both arrays and scalars can be specified as shared. Shared scalars and arrays are common to all the iterations of a DOALL loop. All other scalars and arrays referenced in the DOALL loop, but not contained in the shared list, conform to their appropriate default scoping rules.

Example: Specify a shared variable:

      equivalence (a(1),y)
C$PAR DOALL SHARED(y)
      do i = 1,n
        a(i) = y
      end do

In the preceding example, the variable y has been specified as a variable whose value should be shared among the iterations of the i loop.

`READONLY(varlist)`

The READONLY(varlist) qualifier specifies that all scalars and arrays in the list varlist are read-only for the DOALL loop. Read-only scalars and arrays are a special class of shared scalars and arrays that are not modified in any iteration of the DOALL loop. Specifying scalars and arrays as READONLY indicates to the compiler that it does not need to use a separate copy of that variable or array for each thread of the DOALL loop.

Example: Specify a read-only variable:

      x = 3
C$PAR DOALL SHARED(x),READONLY(x)
      do i = 1, n
        b(i) = x + 1
      end do

In the preceding example, x is a shared variable, but the compiler can rely on the fact that it will not change over each iteration of the i loop because of its READONLY specification.

`STOREBACK(varlist)`

A STOREBACK variable or array is one whose value is computed in a DOALL loop. The computed value can be used after the termination of the loop. In other words, the last loop iteration values of storeback scalars and arrays may be visible outside of the DOALL loop.

Example: Specify the loop index variable as storeback:

C$PAR DOALL PRIVATE(x), STOREBACK(x,i)
      do i = 1, n
        x = ...
      end do
      ... = i
      ... = x

In the preceding example, both the variables x and i are STOREBACK variables, even though both variables are private to the i loop.

There are some potential problems for STOREBACK, however.

The STOREBACK operation occurs at the last iteration of the explicitly parallelized loop, even if this is the same iteration that last updates the value of the STOREBACK variable or array.

Example: STOREBACK variable potentially different from the serial version:

C$PAR DOALL PRIVATE(x), STOREBACK(x)
      do i = 1, n
        if (...) then
            x = ...
        end if
      end do
      print *,x

In the preceding example, the value of the STOREBACK variable x that is printed out might not be the same as that printed out by a serial version of the i loop. In the explicitly parallelized case, the processor that processes the last iteration of the i loop (when i = n) and performs the STOREBACK operation for x, might not be the same processor that currently contains the last updated value of x. The compiler issues a warning message about these potential problems.

In an explicitly parallelized loop, arrays are not treated by default as STOREBACK, so include them in the list varlist if such a storeback operation is desired--for example, if the arrays have been declared as private.

`SAVELAST`

The SAVELAST qualifier specifies that all private scalars and arrays are STOREBACK for the DOALL loop. A STOREBACK variable or array is one whose value is computed in a DOALL loop; this computed value can be used after the termination of the loop. In other words, the last loop iteration values of STOREBACK scalars and arrays may be visible outside of the DOALL loop.

Example: Specify SAVELAST:

C$PAR DOALL PRIVATE(x,y), SAVELAST 
      do i = 1, n
        x = ...
        y = ...
      end do
      ... = i
      ... = x
      ... = y

In the preceding example, variables x, y, and i are STOREBACK variables.

`REDUCTION(varlist)`

The REDUCTION(varlist) qualifier specifies that all variables in the list varlist are reduction variables for the DOALL loop. A reduction variable (or array) is one whose partial values can be individually computed on various processors, and whose final value can be computed from all its partial values.

The presence of a list of reduction variables can aid the compiler in identifying if a DOALL loop is a reduction loop and in generating parallel reduction code for it.

Example: Specify a reduction variable:

C$PAR DOALL REDUCTION(x)
      do i = 1, n
        x = x + a(i)
      end do

In the preceding example, the variable x is a (sum) reduction variable; the i loop is a (sum) reduction loop.

`SCHEDTYPE(t)`

The SCHEDTYPE(t) qualifier specifies that the specific scheduling type t be used to schedule the DOALL loop.

Table 10-5 DOALL SCHEDTYPE Qualifiers


Scheduling Type	Action
`STATIC`	Use static scheduling for this `DO` loop. Distribute all iterations uniformly to all available processors. Example: With 1000 iterations and 4 CPUs each CPU gets a single iteration in turn until all the iterations have been distributed.
`SELF[(chunksize)]`	Use self-scheduling for this `DO` loop. Distribute `chunksize` iterations to each available processor: o Repeat with the remaining iterations until all the iterations have been processed. o If `chunksize` is not provided, `f77` selects a value. Example: With 1000 iterations and `chunksize` of 4, distribute 4 iterations to each CPU.
`FACTORING[(` `m` `)]`	Use factoring scheduling for this `DO` loop. With `n` iterations initially and `k` CPUs, distribute n/(2k) iterations uniformly to each processor until all iterations have been processed. o At least `m` iterations must be assigned to each processor. o There can be one final smaller residual chunk. o If `m` is not provided, `f77` selects a value. Example: With 1000 iterations and `FACTORING`(4), and 4 CPUs, distribute 125 iterations to each CPU, then 62 iterations, then 31 iterations, and so on.
`GSS[(` `m` `)]`	Use guided self-scheduling for this `DO` loop. With `n` iterations initially, and `k` CPUs, then: o Assign n/k iterations to the first processor. o Assign the remaining iterations divided by `k` to the second processor, and so on until all iterations have been processed. Note: o At least `m` iterations must be assigned to each CPU. o There can be one final smaller residual chunk. o If `m` is not provided, `f77` selects a value. Example: With 1000 iterations and `GSS`(10), and 4 CPUs, distribute 250 iterations to the first CPU, then 187 to the second CPU, then 140 to the third CPU, and so on.