Documentation Center

  • Trial Software
  • Product Updates

coder.unroll

Package: coder

Copy body of for-loop in generated code for each iteration

Syntax

for i = coder.unroll(range)
for i = coder.unroll(range,flag)

Description

for i = coder.unroll(range) copies the body of a for-loop (unrolls a for-loop) in generated code for each iteration specified by the bounds in range. i is the loop counter variable.

for i = coder.unroll(range,flag) unrolls a for-loop as specified in range if flag is true.

You must use coder.unroll in a for-loop header. coder.unroll modifies the generated code, but does not change the computed results.

coder.unroll must be able to evaluate the bounds of the for-loop at compile time. The number of iterations cannot exceed 1024; unrolling large loops can increase compile time significantly and generate inefficient code

This function is ignored outside of code generation.

Input Arguments

flag

Boolean expression that indicates whether to unroll the for-loop:

trueUnroll the for-loop
falseDo not unroll the for-loop

range

Specifies the bounds of the for-loop iteration:

init_val : end_valIterate from init_val to end_val, using an increment of 1
init_val : step_val : end_valIterate from init_val to end_val, using step_val as an increment if positive or as a decrement if negative
Matrix variableIterate for a number of times equal to the number of columns in the matrix

Examples

To limit the number of times to copy the body of a for-loop in generated code:

  1. Write a MATLAB® function getrand(n) that uses a for-loop to generate a vector of length n and assign random numbers to specific elements. Add a test function test_unroll. This function calls getrand(n) with n equal to values both less than and greater than the threshold for copying the for-loop in generated code.

    function [y1, y2] = test_unroll() %#codegen
    % The directive %#codegen indicates that the function
    % is intended for code generation
      % Calling getrand 8 times triggers unroll
      y1 = getrand(8);
      % Calling getrand 50 times does not trigger unroll
      y2 = getrand(50);
     
    function y = getrand(n)
      % Turn off inlining to make 
      % generated code easier to read
      coder.inline('never');
    
      % Set flag variable dounroll to repeat loop body
      % only for fewer than 10 iterations
      dounroll = n < 10;
      % Declare size, class, and complexity
      % of variable y by assignment
      y = zeros(n, 1);
      % Loop body begins
      for i = coder.unroll(1:2:n, dounroll)
          if (i > 2) && (i < n-2) 
              y(i) = rand();
          end;
      end;
      % Loop body ends
  2. In the default output folder, codegen/lib/test_unroll, generate C static library code for test_unroll :

    codegen -config:lib test_unroll

    In test_unroll.c, the generated C code for getrand(8) repeats the body of the for-loop (unrolls the loop) because the number of iterations is less than 10:

    static void getrand(double y[8])
    {
      /*  Turn off inlining to make  */
      /*  generated code easier to read */
      /*  Set flag variable dounroll to repeat loop body */
      /*  only for fewer than 10 iterations */
      /*  Declare size, class, and complexity */
      /*  of variable y by assignment */
      memset(&y[0], 0, sizeof(double) << 3);
    
      /*  Loop body begins */
      y[2] = b_rand();
      y[4] = b_rand();
    
      /*  Loop body ends */
    }
    

    The generated C code for getrand(50) does not unroll the for-loop because the number of iterations is greater than 10:

    static void b_getrand(double y[50])
    {
      int i;
      int b_i;
    
      /*  Turn off inlining to make  */
      /*  generated code easier to read */
      /*  Set flag variable dounroll to repeat loop body */
      /*  only for fewer than 10 iterations */
      /*  Declare size, class, and complexity */
      /*  of variable y by assignment */
      memset(&y[0], 0, 50U * sizeof(double));
    
      /*  Loop body begins */
      for (i = 0; i < 25; i++) {
        b_i = (i << 1) + 1;
        if ((b_i > 2) && (b_i < 48)) {
          y[b_i - 1] = b_rand();
        }
      }
    

See Also

| |

Was this topic helpful?