coder.loop.unrollAndJam

R2026b

Unroll and jam for-loops in generated code

Since R2023a

collapse all in page

    Syntax

    coder.loop.unrollAndJam(loopID,unrollFactor)

    Description

    coder.loop.unrollAndJam(loopID,unrollFactor) prompts the code generator to unroll the loop identified by loopID by a factor of unrollFactor and combine the resulting inner loop computations across iterations into a single, larger inner loop body in the generated code.

    Use this directive for perfectly nested loops, where all computation occurs in the innermost loop and the code contains no statements between loop levels. This directive is most effective for small, compute-dense loop bodies and helps remove loop overhead and improve data reuse. It can be less beneficial for large or complex loops. The loop size must be perfectly divisible by the unrollFactor argument. For more information about loop optimizations, see Optimize Loops in Generated Code.

    example

    Examples

    collapse all

    Examine the function loopUnrollAndJam, which uses a local function to compute i^2+j^2 for each element of a matrix. The function uses the coder.loop.unrollAndJam directive to unroll and combine the computations inside the for-loop.

    function out = loopUnrollAndJam %#codegen
out = zeros(10);

coder.loop.unrollAndJam("i",5);
for i = 1:10
    for j = 1:10
        out(i,j) = out(i,j) + local(i,j);
    end
end
end

function y = local(x,z)
y = x^2 + z^2;
end

    Generate a C static library for this function.

    codegen -config:lib -report loopUnrollAndJam

    Open the code generation report and inspect the generated code for the function. The code generator unrolls the outer loop and merges the operations from each unrolled iteration into a single inner loop.

    for (i = 0; i <= 5; i += 5) {
    for (j = 0; j < 10; j++) {
      int b_out_tmp;
      int out_tmp;
      out_tmp = i + 10 * j;
      b_out_tmp = (j + 1) * (j + 1);
      out[out_tmp] += (double)((i + 1) * (i + 1) + b_out_tmp);
      out[out_tmp + 1] += (double)((i + 2) * (i + 2) + b_out_tmp);
      out[out_tmp + 2] += (double)((i + 3) * (i + 3) + b_out_tmp);
      out[out_tmp + 3] += (double)((i + 4) * (i + 4) + b_out_tmp);
      out[out_tmp + 4] += (double)((i + 5) * (i + 5) + b_out_tmp);
    }
  }

    Input Arguments

    collapse all

    Index name for the for-loop to unroll and jam, specified as a string scalar or character vector.

    Factor by which to unroll the loop in the generated code, specified as an integer.

    Limitations

    • Because of internal, low-level optimizations during code generation, the generated code can contain an imperfectly nested loop, even when the corresponding loop in the MATLAB® code is perfectly nested. Under these circumstances, the code generator cannot apply the unrollAndJam directive.

    Tips

    • To view potential issues that the code generator encounters when applying the coder.loop.unrollAndJam directive, review the Code Insights section of the code generation report. See Code Generation Reports.

    Extended Capabilities

    expand all

    C/C++ Code Generation
    Generate C and C++ code using MATLAB® Coder™.

    GPU Code Generation
    Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

    Version History

    Introduced in R2023a

    See Also

    |

    Topics