Main Content

coder.loop.parallelize

Parallelize specific for loops in generated code; disable automatic parallelization

Since R2021a

collapse all in page

    Syntax

    coder.loop.parallelize('never')
    coder.loop.parallelize("loopID")
    loopObj = coder.loop.parallelize(___)

    Description

    coder.loop.parallelize('never') disables automatic parallelization of the for loop placed immediately after it. This pragma overrides the EnableAutoParallelization configuration setting.

    This pragma supports explicit for loops only. For more information on explicit and implicit loops, see Parallelize Implicit for Loops.

    example

    coder.loop.parallelize("loopID") parallelizes the for-loop whose index name is loopID.

    This prompts the generated code for that loop to execute the iterations in parallel with the threads available for your target. This transforms requires EnableOpenMP to be set to true in your code configuration object.

    For more information about loop optimizations, see Optimize Loops in Generated Code.

    loopObj = coder.loop.parallelize(___) creates a loop control object with transformSchedule property set to coder.loop.parallelize. Use the apply method to apply the transform to the specified loop.

    Examples

    collapse all

    This example shows how to disable the automatic parallelization of a specific for loop in your MATLAB® code by using the coder.loop.parallelize('never') directive.

    Define the MATLAB function autoparExample:

    function [x, y] = autoparExample(x, y) %#codegen
x = x * 17;
% Pragma to disable automatic parallelization of for-loops
coder.loop.parallelize('never');
for i = 10:numel(x)
    y(i) = sqrt(y(i));
end
end

    This function contains two loops:

    • The mtimes (matrix multiplication) function contains an implicit for loop that iterates over the elements of the matrix x.

    • The explicit for loop that calculates the square root of a subset of the elements of the matrix y. The coder.loop.parallelize('never') directive disables automatic parallelization of this loop.

    Create a code generation configuration object for a static library. Set the EnableAutoParallelization property to true. Specify the input types as 1-by-2000 row vectors of doubles and generate code.

    cfg = coder.config('lib');
cfg.EnableAutoParallelization = 1;
codegen -config cfg autoparExample -args {rand(1,2000) rand(1,2000)} -report
    Code generation successful: View report

    Open the code generation report and inspect the generated autoparExample function:

    • The generated code contains a parallel loop for the multiplication operation.

    • The explicit for loop is converted to a serial loop in the generated code. This loop was preceded by the coder.loop.parallelize('never') directive in your MATLAB code. The code generator does not parallelize it.

    void autoparExample(double x[2000], double y[2000])
{
  int b_i;
  int i;
  if (!isInitialized_autoparExample) {
    autoparExample_initialize();
  }
#pragma omp parallel for num_threads(omp_get_max_threads()) private(i)

  for (i = 0; i < 2000; i++) {
    x[i] *= 17.0;
  }
  /*  Pragma to disable automatic parallelization of for-loops */
  for (b_i = 0; b_i < 1991; b_i++) {
    y[b_i + 9] = sqrt(y[b_i + 9]);
  }
}
    Open Live Script

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

    Define a MATLAB function forLoopFuncParallel. Within the function, call coder.loop.parallelize with the for-loop index to be parallelized. Also call the function to prevent parallelization of a specific loop.

    type forLoopFuncParallel
    function [out1,out2] = forLoopFuncParallel
out1 = ones(1,100);
out2 = zeros(1,100);

coder.loop.parallelize("i");
for i = 1:100
    out1(i) = out1(i) * i;
end

coder.loop.parallelize("j","never");
for j = 1:100
    out2(j) = out2(j) + j;
end

    Generate code for this function at the command line.

    codegen forLoopFuncParallel -config:lib
    Warning: Code generation is using a coder.EmbeddedCodeConfig object. Because
Embedded Coder is not installed, this might cause some Embedded Coder features
to fail.

Code generation successful (with warnings): To view the report, open('codegen/lib/forLoopFuncParallel/html/report.mldatx')

    Inspect the generated code. The code generator uses OpenMP to parallelize the loop.

    type(fullfile("codegen","lib","forLoopFuncParallel","forLoopFuncParallel.c"))
    /*
 * File: forLoopFuncParallel.c
 *
 * MATLAB Coder version            : 24.2
 * C/C++ source code generated on  : 05-Sep-2024 16:35:58
 */

/* Include Files */
#include "forLoopFuncParallel.h"
#include "forLoopFuncParallel_data.h"
#include "forLoopFuncParallel_initialize.h"
#include "omp.h"

/* Function Definitions */
/*
 * Arguments    : double out1[100]
 *                double out2[100]
 * Return Type  : void
 */
void forLoopFuncParallel(double out1[100], double out2[100])
{
  int i;
  int j;
  if (!isInitialized_forLoopFuncParallel) {
    forLoopFuncParallel_initialize();
  }
  for (j = 0; j < 100; j++) {
    out1[j] = 1.0;
    out2[j] = 0.0;
  }
#pragma omp parallel for num_threads(omp_get_max_threads())

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

/*
 * File trailer for forLoopFuncParallel.c
 *
 * [EOF]
 */

    Input Arguments

    collapse all

    for loop identifier or index name to parallelize, specified as a character vector a string scalar.

    Data Types: char | string

    Output Arguments

    collapse all

    Loop control object with transformSchedule property set to coder.loop.parallelize.

    Extended Capabilities

    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