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
  You can have a parfor loop inside another parfor-loop. However, the inner parfor loop will be executed on a single thread as an ordinary for-loop.
  Inside a parfor loop, you can call a function that contains another parfor-loop.
- Break and return statements
  You cannot use break or return statements inside a parfor-loop.
- Global variables
  You cannot write to a global variable inside a parfor-loop.
- Reductions on MATLAB classes
  You cannot use reductions on MATLAB classes inside a parfor-loop.
- Reductions on char variables
  You cannot use reductions on char variables inside a parfor-loop.
  For example, you cannot generate C code for the following MATLAB code:
  c = char(0); parfor i=1:10 c = c + char(1); end
  In the parfor-loop, MATLAB makes c a double. For code generation, c cannot change type.
- Reductions using external C code
  You cannot use coder.ceval in reductions inside a parfor-loop.. For example, you cannot generate code for the following parfor-loop:
  parfor i=1:4 y=coder.ceval('myCFcn',y,i); end
  Instead, write a local function that calls the C code using coder.ceval and call this function in the parfor-loop. For example:
  parfor i=1:4 y = callMyCFcn(y,i); end ... function y = callMyCFcn(y,i) y = coder.ceval('mCyFcn', y , i); end
- Extrinsic function calls
  You cannot call extrinsic functions using coder.extrinsic inside a parfor-loop. Calls to functions that contain extrinsic calls result in a run-time error.
- Inlining functions
  MATLAB Coder does not inline functions into parfor-loops, including functions that use coder.inline('always').
- Unrolling loops
  You cannot use coder.unroll inside a parfor-loop.
  If a loop is unrolled inside a parfor-loop, MATLAB Coder cannot classify the variable. For example:
  for j=coder.unroll(3:6) y(i,j)=y(i,j)+i+j; end
  This code is unrolled to:
  y(i,3)=y(i,3)+i+3; ... y(i,6)=y(i,6)+i+6;
  In the unrolled code, MATLAB Coder cannot classify the variable y because y is indexed in different ways inside the parfor-loop.
  MATLAB Coder does not support variables that it cannot classify. For more information, see Classification of Variables in parfor-Loops.
- varargin/varargout
  You cannot use varargin or varargout inside a parfor-loop.