parfor

Parallel for-loop

Syntax

parfor LoopVar = InitVal:EndVal; Statements; end

parfor (LoopVar = InitVal:EndVal, NumThreads); Statements; end

Description

parfor LoopVar = InitVal:EndVal; Statements; end creates a loop in a generated MEX function or in C/C++ code that runs in parallel on shared-memory multicore platforms.

The parfor-loop executes the Statements for values of LoopVar between InitVal and Endval. LoopVar specifies a vector of integer values increasing by 1.

parfor (LoopVar = InitVal:EndVal, NumThreads); Statements; end uses a maximum of NumThreads threads when creating a parallel for-loop.

Examples

Generate MEX for parfor

Generate a MEX function for a parfor-loop to execute on the maximum number of cores available.

Write a MATLAB^® function, test_parfor, that calls the fast Fourier transform function, fft, in a parfor-loop. Because the loop iterations run in parallel, this evaluation can be completed much faster than an analogous for-loop.

function a = test_parfor %#codegen
  a = ones(10,256);  
  r = rand(10,256);
  parfor i = 1:10
    a(i,:) = real(fft(r(i)));
  end
end

Generate a MEX function for test_parfor. At the MATLAB command line, enter:

codegen test_parfor

codegen generates a MEX function, test_parfor_mex, in the current folder.

Run the MEX function. At the MATLAB command line, enter:

test_parfor_mex

The MEX function runs using the available cores.

Specify Maximum Number of Threads for parfor

Specify the maximum number of threads when generating a MEX function for a parfor-loop.

Write a MATLAB function, specify_num_threads, that uses input, u, to specify the maximum number of threads in the parfor-loop.

function y = specify_num_threads(u) %#codegen
  y = ones(1,100);
  % u specifies maximum number of threads
  parfor (i = 1:100,u)
    y(i) = i;
  end
end

Generate a MEX function for specify_num_threads. Use -args 0 to specify the type of the input. At the MATLAB command line, enter:

% -args 0 specifies that input u is a scalar double
% u is typecast to an integer by the code generator
codegen -report specify_num_threads -args 0

codegen generates a MEX function, specify_num_threads_mex, in the current folder.

Run the MEX function, specifying that it run in parallel on at most four threads. At the MATLAB command line, enter:

specify_num_threads_mex(4)

The generated MEX function runs on up to four cores. If fewer than four cores are available, the MEX function runs on the maximum number of cores available at the time of the call.

Generate MEX for parfor Without Parallelization

Disable parallelization before generating a MEX function for a parfor-loop.

Write a MATLAB function, test_parfor, that calls the fast Fourier transform function, fft, in a parfor-loop.

function a = test_parfor %#codegen
  a = ones(10,256);  
  r = rand(10,256);
  parfor i = 1:10
    a(i,:) = real(fft(r(i)));
  end
end

Generate a MEX function for test_parfor. Disable the use of OpenMP so that codegen does not generate a MEX function that can run on multiple threads.

codegen -O disable:OpenMP test_parfor

codegen generates a MEX function, test_parfor_mex, in the current folder.

Run the MEX function.

test_parfor_mex

The MEX function runs on a single thread.

If you disable parallelization, MATLAB Coder™ treats parfor-loops as for-loops. The software generates a MEX function that runs on a single thread. Disable parallelization to compare performance of the serial and parallel versions of the generated MEX function or C/C++ code. You can also disable parallelization to debug issues with the parallel version.

Input Arguments

LoopVar — Loop index

integer

Loop index variable whose initial value is InitVal and final value is EndVal.

InitVal — Initial value of loop index

integer

Initial value for loop index variable, Loopvar. With EndVal, specifies the parfor range vector, which must be of the form M:N.

EndVal — Final value of loop index

integer

Final value for loop index variable, LoopVar. With InitVal, specifies the parfor range vector, which must be of the form M:N.

Statements — Loop body

text

The series of MATLAB commands to execute in the parfor-loop.

If you put more than one statement on the same line, separate the statements with semicolons. For example:

parfor i = 1:10
 arr(i) = rand(); arr(i) = 2*arr(i)-1;
end

NumThreads — Maximum number of threads running in parallel

number of available cores (default) | nonnegative integer

Maximum number of threads to use. If you specify the upper limit, MATLAB Coder uses no more than this number, even if additional cores are available. If you request more threads than the number of available cores, MATLAB Coder uses the maximum number of cores available at the time of the call. If the loop iterations are fewer than the threads, some threads perform no work.

If the parfor-loop cannot run on multiple threads (for example, if only one core is available or NumThreads is 0), MATLAB Coder executes the loop in a serial manner.

Limitations

• 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.

• Do not use the following constructs inside parfor-loops:

  • You cannot call extrinsic functions using coder.extrinsic in the body of a parfor-loop.

  • You cannot write to a global variable inside a parfor-loop.

  • MATLAB Coder does not support the use of coder.ceval in reductions. 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

  • You cannot use varargin or varargout in parfor-loops.

• 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.

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

For a comprehensive list of restrictions, see parfor Restrictions.

Tips

• Use a parfor-loop when:

  • You need many loop iterations of a simple calculation. parfor divides the loop iterations into groups so that each thread can execute one group of iterations.

  • You have loop iterations that take a long time to execute.

• Do not use a parfor-loop when an iteration in your loop depends on the results of other iterations.

  Reductions are one exception to this rule. A reduction variable accumulates a value that depends on all the iterations together, but is independent of the iteration order.

• The input argument NumThreads sets the OpenMP num_threads() clause in the generated code. OpenMP also supports globally limiting the number of threads in C/C++ by setting the environment variable OMP_NUM_THREADS or by using omp_set_num_threads(). For more information, see the openMP specifications. https://www.openmp.org/specifications/

Version History

Introduced in R2012b