Main Content

parfor

Parallel for-loop

collapse all in page

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.

example

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

example

Examples

collapse all

Generate a MEX function and a standalone C library for a MATLAB® function that contains a parfor-loop. Instruct the code generator to use the maximum number of available cores.

Define 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 command line. Do not specify a maximum number of threads.

codegen test_parfor

Run the MEX function at the command line. The MEX function uses the available cores.

test_parfor_mex

Generate a standalone C library for test_parfor. Do not specify a maximum number of threads. The generated C code executes the loop iterations in parallel on the available cores.

codegen -config:lib test_parfor

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

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

function y = specify_num_threads(u) %#codegen
  y = ones(1,100);
  parfor (i = 1:100,u)
    y(i) = i;
  end
end

Generate a MEX function for specify_num_threads. Use -args 0 to specify that u is a scalar double.

codegen specify_num_threads -args 0

Run the generated MEX function, specifying that the function run in parallel on at most four threads. 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.

specify_num_threads_mex(4)

Generate C code for test_parfor. Use -args 0 to specify that u is a scalar double. In the generated code, the iterations of the parfor-loop run on at most u cores. If fewer cores are available, the iterations run on the cores available at the time of the call.

codegen -config:lib test_parfor -args 0

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

collapse all

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

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

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

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

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.

  • 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

See Also

Functions

Topics