coder.loop.parallelize

R2026b

Parallelize for-loops in generated code or disable automatic parallelization

collapse all in page

    Syntax

    coder.loop.parallelize(loopID)
    coder.loop.parallelize(loopID,"never")

    Description

    coder.loop.parallelize(loopID) parallelizes the for-loop with index name loopID. The code generator produces code that executes the iterations of the specified loop in parallel using available target threads. To use this directive, your compiler must support the OpenMP library, and you must enable the Enable dynamic memory allocation and Enable OpenMP library if possible parameters. See Automatic Parallelization of for-Loops in the Generated Code.

    Use this directive for for-loops that have many iterations and perform independent, non-trivial work in each iteration. To effectively parallelize across multiple CPU cores, the code generator must be able to divide loop iterations evenly across threads. Because parallelization introduces overhead, this directive works best for loops with efficient memory access. For more information about loop optimizations, see Optimize Loops in Generated Code.

    example

    coder.loop.parallelize(loopID,"never") disables automatic parallelization of the for-loop that immediately follows this function call in the generated code. This directive overrides the EnableAutoParallelization configuration setting. This directive supports explicit for-loops only. For more information on explicit and implicit loops, see Parallelization of Explicit and Implicit for-loops.

    Automatic parallelization of for-loops can improve performance by distributing work across threads. Disable parallelization for loops with low work per iteration, irregular memory access patterns, or dependencies among iterations, as the added overhead can reduce or negate performance gains.

    example

    Examples

    collapse all

    You can choose to parallelize specific for-loops in the generated code by using the coder.loop.parallelize function in your MATLAB® code.

    Examine the function forLoopFuncParallel. This function uses coder.loop.parallelize("i","never") to prevent the automatic parallelization of the for-loop with loop index i and uses coder.loop.parallelize("j") to force the parallelization of the for-loop with loop index j.

    function [out1,out2] = forLoopFuncParallel %#codegen
out1 = ones(1,100);
out2 = ones(1,100);

% Disable parallelization
coder.loop.parallelize("i","never");
for i = 2:100
    out1(i) = out1(i - 1)+i;
end


% Force parallelization
coder.loop.parallelize("j");
for j = 1:100
    out2(j) = out2(j)*j;
end
end

    Inspect the generated code. The code generator does not parallelize the first loop, and it uses OpenMP to parallelize the second loop. 

      /*  Disable parallelization */
  for (i = 0; i < 99; i++) {
    out1[i + 1] = out1[i] + ((double)i + 2.0);
  }
  /*  Force parallelization */
#pragma omp parallel for num_threads(omp_get_max_threads())

  for (j = 0; j < 100; j++) {
    out2[j] *= (double)j + 1.0;
  }

    This example shows how to disable the automatic parallelization of an explicit for-loop in your MATLAB code.

    Examine the function disableParExample. The function uses explicit for-loops to calculate the square root of a subset of the elements of the matrices x and y. The function disables the automatic parallelization of the second loop.

    function [x,y] = disableParExample(in) %#codegen
x = rand(100,100);
y = rand(100,100);

% Automatic parallelization
for i = 1:in
    x(i) = sqrt(x(i));
end

% Disable parallelization
coder.loop.parallelize("j","never");
for j = 1:in
    y(j) = sqrt(y(j));
end
end

    Generate a C static library for this function.

    codegen -config:lib -report disableParExample

    Open the code generation report and inspect the generated disableParExample function. The generated code automatically parallelizes the first for-loop. It uses a serial for-loop to perform the second operation.

      /*  Automatic parallelization */
  i = (int)in;
  scalarLB = ((int)in / 2) << 1;
  vectorUB = scalarLB - 2;
  for (b_i = 0; b_i <= vectorUB; b_i += 2) {
    _mm_storeu_pd(&x[b_i], _mm_sqrt_pd(_mm_loadu_pd(&x[b_i])));
  }
  for (b_i = scalarLB; b_i < i; b_i++) {
    x[b_i] = sqrt(x[b_i]);
  }
  /*  Disable parallelization */
  vectorUB = scalarLB - 2;
  for (b_i = 0; b_i <= vectorUB; b_i += 2) {
    _mm_storeu_pd(&y[b_i], _mm_sqrt_pd(_mm_loadu_pd(&y[b_i])));
  }
  for (b_i = scalarLB; b_i < i; b_i++) {
    y[b_i] = sqrt(y[b_i]);
  }

    Input Arguments

    collapse all

    Index of the for-loop to parallelize, specified as a string scalar or character vector.

    Limitations

    Tips

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

    • Use the coder.loop.parallelize function and the coder.loop.Control.parallelize method to parallelize generated code. To parallelize both the MATLAB code and the generated code, use a parfor-loop instead of a for-loop. See Algorithm Acceleration Using Parallel for-Loops (parfor).

    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 R2021a

    See Also

    |

    Topics