#pragma unroll

Purpose

Controls loop unrolling, for improved performance.

When unroll is in effect, the optimizer determines and applies the best unrolling factor for each loop; in some cases, the loop control might be modified to avoid unnecessary branching. The compiler remains the final arbiter of whether the loop is unrolled.

Syntax

Defaults

See the description of the UNROLL option in the z/OS XL C/C++ User's Guide

Parameters

The following suboptions are for -qunroll only:

n: Instructs the compiler to unroll loops by a factor of n. In other words, the body of a loop is replicated to create n copies and the number of iterations is reduced by a factor of 1/n. The -qunroll=n option specifies a global unroll factor that affects all loops that do not already have an unroll pragma. The value of n must be a positive integer.; Specifying #pragma unroll(1) or -qunroll=1 disables loop unrolling, and is equivalent to specifying #pragma nounroll or -qnounroll.; The compiler might limit unrolling to a number smaller than the value you specify for n. This is because the option form affects all loops in source files to which it applies and large unrolling factors might significantly increase compile time without necessarily improving runtime performance. To specify an unrolling factor for particular loops, use the #pragma form in those loops.

Usage

The pragma overrides the [NO]UNROLL option setting for a designated loop. However, even if #pragma unroll is specified for a given loop, the compiler remains the final arbiter of whether the loop is unrolled.

Only one pragma can be specified on a loop.

The pragma affects only the loop that follows it. An inner nested loop requires a #pragma unroll directive to precede it if the wanted loop unrolling strategy is different from that of the prevailing [NO]UNROLL option.

The #pragma unroll and #pragma nounroll directives can only be used on for loops. They cannot be applied to do while and while loops.

The loop structure must meet the following conditions:

There must be only one loop counter variable, one increment point for that variable, and one termination variable. These cannot be altered at any point in the loop nest.
Loops cannot have multiple entry and exit points. The loop termination must be the only means to exit the loop.
Dependencies in the loop must not be "backwards-looking". For example, a statement such as A[i][j] = A[i -1][j + 1] + 4 must not appear within the loop.

Predefined macros

None.

Examples

In the following example, the #pragma unroll(3) directive on the first for loop requires the compiler to replicate the body of the loop three times. The #pragma unroll on the second for loop allows the compiler to decide whether to perform unrolling.

#pragma unroll(3)
for( i=0;i < n; i++)
{
      a[i] = b[i] * c[i];
}

#pragma unroll
for( j=0;j < n; j++)
{
      a[j] = b[j] * c[j];

}

In this example, the first #pragma unroll(3) directive results in:

i=0;
if (i>n-2) goto remainder;
for (; i<n-2; i+=3) { 
  a[i]=b[i] * c[i];
  a[i+1]=b[i+1] * c[i+1]; 
  a[i+2]=b[i+2] * c[i+2]; 
} 
if (i<n) { 
  remainder: 
  for (; i<n; i++) { 
    a[i]=b[i] * c[i]; 
  } 
}

Related information

The UNROLL option in the z/OS XL C/C++ User's Guide