DO Directive

OpenMP* Fortran Compiler Directive: Specifies that the iterations of the immediately following DO loop must be executed in parallel.

Syntax

c$OMP DO [clause[[,] clause] ... ]

do_loop

[c$OMP END DO [NOWAIT]]

Is one of the following: C (or c), !, or * (see Syntax Rules for Compiler Directives).

clause

Is one of the following:

FIRSTPRIVATE (list)
LASTPRIVATE (list)
ORDERED

Must be used if ordered sections are contained in the dynamic extent of the DO directive. For more information about ordered sections, see the ORDERED directive.
PRIVATE (list)
REDUCTION (operator | intrinsic : list)
COLLAPSE (n)

Specifies how many loops are associated with the loop construct. Then must be a constant positive integer expression. If COLLAPSE is not specified, the only loop that is associated with the loop construct is the one that immediately follows the construct.

If n is greater than one, the iterations of all associated loops are collapsed into one larger iteration, which is then divided according to the SCHEDULE clause. The sequential execution of the iterations in all associated loops determines the order of the iterations in the collapsed iteration.

The iteration count for each associated loop is computed before entry to the outermost loop.

SCHEDULE (type[, chunk])

Specifies how iterations of the DO loop are divided among the threads of the team. chunk must be a scalar integer expression. The following four types are permitted, three of which allow the optional parameter chunk:

Type	Effect
STATIC	Divides iterations into contiguous pieces by dividing the number of iterations by the number of threads in the team. Each piece is then dispatched to a thread before loop execution begins. If `chunk` is specified, iterations are divided into pieces of a size specified by `chunk`. The pieces are statically dispatched to threads in the team in a round-robin fashion in the order of the thread number.
DYNAMIC	Can be used to get a set of iterations dynamically. It defaults to 1 unless `chunk` is specified. If `chunk` is specified, the iterations are broken into pieces of a size specified by `chunk`. As each thread finishes a piece of the iteration space, it dynamically gets the next set of iterations.
GUIDED	Can be used to specify a minimum number of iterations. It defaults to 1 unless `chunk` is specified. If `chunk` is specified, the chunksize is reduced exponentially with each succeeding dispatch. The `chunk` specifies the minimum number of iterations to dispatch each time. If there are less than `chunk` iterations remaining, the rest are dispatched.
AUTO¹	Delegates the scheduling decision until compile time or run time. The schedule is processor dependent. The programmer gives the implementation the freedom to choose any possible mapping of iterations to threads in the team.
RUNTIME¹	Defers the scheduling decision until run time. You can choose a schedule type and chunksize at run time by using the environment variable OMP_SCHEDULE.
¹No `chunk` is permitted for this type.

If the SCHEDULE clause is not used, the default schedule type is STATIC.

do_loop

Is a DO iteration (an iterative DO loop). It cannot be a DO WHILE or a DO loop without loop control. The DO loop iteration variable must be of type integer.

The iterations of the DO loop are distributed across the existing team of threads. The values of the loop control parameters of the DO loop associated with a DO directive must be the same for all the threads in the team.

You cannot branch out of a DO loop associated with a DO directive.

If used, the END DO directive must appear immediately after the end of the loop. If you do not specify an END DO directive, an END DO directive is assumed at the end of the DO loop.

If you specify NOWAIT in the END DO directive, threads do not synchronize at the end of the parallel loop. Threads that finish early proceed straight to the instruction following the loop without waiting for the other members of the team to finish the DO directive.

Parallel DO loop control variables are block-level entities within the DO loop. If the loop control variable also appears in the LASTPRIVATE list of the parallel DO, it is copied out to a variable of the same name in the enclosing PARALLEL region. The variable in the enclosing PARALLEL region must be SHARED if it is specified in the LASTPRIVATE list of a DO directive.

Only a single SCHEDULE, COLLAPSE, or ORDERED clause can appear in a DO directive.

DO directives must be encountered by all threads in a team or by none at all. It must also be encountered in the same order by all threads in a team.

Example

In the following example, the loop iteration variable is private by default, and it is not necessary to explicitly declare it. The END DO directive is optional:

  c$OMP PARALLEL

  c$OMP DO

        DO I=1,N

          B(I) = (A(I) + A(I-1)) / 2.0

        END DO

  c$OMP END DO

  c$OMP END PARALLEL

If there are multiple independent loops within a parallel region, you can use the NOWAIT option to avoid the implied BARRIER at the end of the DO directive, as follows:

  c$OMP PARALLEL

  c$OMP DO

        DO I=2,N

          B(I) = (A(I) + A(I-1)) / 2.0

        END DO

  c$OMP END DO NOWAIT

  c$OMP DO

        DO I=1,M

          Y(I) = SQRT(Z(I))

        END DO

  c$OMP END DO NOWAIT

  c$OMP END PARALLEL

Correct execution sometimes depends on the value that the last iteration of a loop assigns to a variable. Such programs must list all such variables as arguments to a LASTPRIVATE clause so that the values of the variables are the same as when the loop is executed sequentially, as follows:

  c$OMP PARALLEL

  c$OMP DO LASTPRIVATE(I)

        DO I=1,N

          A(I) = B(I) + C(I)

        END DO

  c$OMP END PARALLEL

        CALL REVERSE(I)

In this case, the value of I at the end of the parallel region equals N+1, as in the sequential case.

Ordered sections are useful for sequentially ordering the output from work that is done in parallel. Assuming that a reentrant I/O library exists, the following program prints out the indexes in sequential order:

  c$OMP DO ORDERED SCHEDULE(DYNAMIC)

        DO I=LB,UB,ST

          CALL WORK(I)

        END DO

...

        SUBROUTINE WORK(K)

  c$OMP ORDERED

        WRITE(*,*) K

  c$OMP END ORDERED

In the next example, the loops over J1 and J2 are collapsed and their iteration space is executed by all threads of the current team:

!$OMP DO COLLAPSE(2) PRIVATE(J1, J2, J3)

    DO J1 = J1_L, J1_U, J1_S

        DO J2 = J2_L, J2_U, J2_S

            DO J3 = J3_L, J3_U, J3_S

                CALL BAR(A, J1, J2, J3)

            ENDDO

        ENDDO

    ENDDO

!$OMP END DO

DO Directive

Syntax

Example

See Also