Main Content

Algorithm Acceleration Using Parallel for-Loops (parfor)

Parallel for-Loops (parfor) in Generated Code

To potentially accelerate execution, you can generate MEX functions or C/C++ code from MATLAB® code that contains parallel for-loops (parfor-loops).

A parfor-loop, like the standard MATLAB for-loop, executes a series of statements (the loop body) over a range of values. Unlike the for-loop, however, the iterations of the parfor-loop can run in parallel on multiple cores on the target hardware.

Running the iterations in parallel might significantly improve execution speed of the generated code. For more information, see How parfor-Loops Improve Execution Speed.

Note

The parallel execution occurs only in generated MEX functions or C/C++ code; not the original MATLAB code. To accelerate your MATLAB code, generate a MEX function from the parfor-loop. Then, call the MEX function from your code. For more information, see Workflow for Accelerating MATLAB Algorithms.

To use parfor in your MATLAB code, you require a Parallel Computing Toolbox™ license.

MATLAB Coder™ software uses the Open Multiprocessing (OpenMP) application interface to support shared-memory, multicore code generation. If you want distributed parallelism, use the Parallel Computing Toolbox product. By default, MATLAB Coder uses up to as many cores as it finds available. If you specify the number of threads to use, MATLAB Coder uses at most that number of cores for the threads, even if additional cores are available. For more information, see parfor.

Because the loop body can execute in parallel on multiple threads, it must conform to certain restrictions. If MATLAB Coder software detects loops that do not conform to parfor specifications, it produces an error. For more information, see parfor Restrictions.

How parfor-Loops Improve Execution Speed

A parfor-loop might provide better execution speed than its analogous for-loop because several threads can compute concurrently on the same loop.

Each execution of the body of a parfor-loop is called an iteration. The threads evaluate iterations in arbitrary order and independently of each other. Because each iteration is independent, they do not have to be synchronized. If the number of threads is equal to the number of loop iterations, each thread performs one iteration of the loop. If there are more iterations than threads, some threads perform more than one loop iteration.

For example, when a loop of 100 iterations runs on 20 threads, each thread executes five iterations of the loop simultaneously. If your loop takes a long time to run because of the large number of iterations or individual iterations being lengthy, you can reduce the run time significantly using multiple threads. In this example, you might not, however, get 20 times improvement in speed because of parallelization overheads, such as thread creation and deletion.

When to Use parfor-Loops

Use parfor when you have:

  • Many iterations of a simple calculation. parfor divides the loop iterations into groups so that each thread executes one group of iterations.

  • A loop iteration that takes a long time to execute. parfor executes the iterations simultaneously on different threads. Although this simultaneous execution does not reduce the time spent on an individual iteration, it might significantly reduce overall time spent on the loop.

When Not to Use parfor-Loops

Do not use parfor when:

  • An iteration of your loop depends on other iterations. Running the iterations in parallel can lead to erroneous results.

    To help you avoid using parfor when an iteration of your loop depends on other iterations, MATLAB Coder specifies a rigid classification of variables. For more information, see Classification of Variables in parfor-Loops. If MATLAB Coder detects loops that do not conform to the parfor specifications, it does not generate code and produces an error.

    Reductions are an exception to the rule that loop iterations must be independent. A reduction variable accumulates a value that depends on all the iterations together, but is independent of the iteration order. For more information, see Reduction Variables.

  • There are only a few iterations that perform some simple calculations.

    Note

    For small number of loop iterations, you might not accelerate execution due to parallelization overheads. Such overheads include time taken for thread creation, data synchronization between threads, and thread deletion.

parfor-Loop Syntax

  • For a parfor-loop, use this syntax:

    parfor i = InitVal:EndVal 
    parfor (i = InitVal:EndVal) 
    

  • To specify the maximum number of threads, use this syntax:

    parfor (i = InitVal:EndVal,NumThreads) 
    

For more information, see parfor.

parfor Restrictions

  • The parfor loop does not support the syntax:

    parfor (i=initVal:step:endVal) 
    parfor i=initVal:step:endVal

  • You must use a compiler that supports the Open Multiprocessing (OpenMP) application interface. See Supported Compilers. If you use a compiler that does not support OpenMP, MATLAB Coder treats the parfor-loops as for-loops. In the generated MEX function or C/C++ code, the loop iterations run on a single thread.

  • The OpenMP application interface is not compatible with JIT MEX compilation. See JIT Compilation Does Not Support OpenMP.

  • The type of the loop index must be representable by an integer type on the target hardware. Use a type that does not require a multiword type in the generated code.

  • parfor for standalone code generation requires the toolchain approach for building executables or libraries. Do not change settings that cause the code generator to use the template makefile approach. See Project or Configuration Is Using the Template Makefile.

  • Do not use the following constructs in the body of a parfor loop:

    •  Nested parfor-loops

    •  Break and return statements

    •  Global variables

    •  Reductions on MATLAB classes

    •  Reductions on char variables

    •  Reductions using external C code

    •  Extrinsic function calls

    •  Inlining functions

    •  Unrolling loops

    •  varargin/varargout