Syntax

Description

parfor loopvar = initval:endval, statements, end allows you to write a loop for a statement or block of code that executes in parallel on a cluster of workers, which are identified and reserved with the parpool command. initval and endval must evaluate to finite integer values, or the range must evaluate to a value that can be obtained by such an expression, that is, an ascending row vector of consecutive integers.

The following table lists some ranges that are not valid.

You can enter a parfor-loop on multiple lines, but if you put more than one segment of the loop statement on the same line, separate the segments with commas or semicolons:

parfor i = range; <loop body>; end

parfor (loopvar = initval:endval, M), statements, end uses M to specify the maximum number of MATLAB^® workers that will evaluate statements in the body of the parfor-loop. M must be a nonnegative integer. By default, MATLAB uses as many workers as it finds available. If you specify an upper limit, MATLAB employs no more than that number, even if additional workers are available. If you request more resources than are available, MATLAB uses the maximum number available at the time of the call.

If the parfor-loop cannot run on workers in a parallel pool (for example, if no workers are available or M is 0), MATLAB executes the loop on the client in a serial manner. In this situation, the parfor semantics are preserved in that the loop iterations can execute in any order.

Note   Because of independence of iteration order, execution of parfor does not guarantee deterministic results.

The maximum amount of data that can be transferred in a single chunk between client and workers in the execution of a parfor-loop is determined by the JVM™ memory allocation limit. For details, see Object Data Size Limitations.

For a detailed description of parfor-loops, see Parallel for-Loops (parfor).

Examples

Suppose that f is a time-consuming function to compute, and that you want to compute its value on each element of array A and place the corresponding results in array B:

parfor i = 1:length(A)
   B(i) = f(A(i));
end

Because the loop iteration occurs in parallel, this evaluation can complete much faster than it would in an analogous for-loop.

Next assume that A, B, and C are variables and that f, g, and h are functions:

parfor i = 1:n
   t = f(A(i));
   u = g(B(i));
   C(i) = h(t,u);
end

If the time to compute f, g, and h is large, parfor will be significantly faster than the corresponding for statement, even if n is relatively small. Although the form of this statement is similar to a for statement, the behavior can be significantly different. Notably, the assignments to the variables i, t, and u do not affect variables with the same name in the context of the parfor statement. The rationale is that the body of the parfor is executed in parallel for all values of i, and there is no deterministic way to say what the "final" values of these variables are. Thus, parfor is defined to leave these variables unaffected in the context of the parfor statement. By contrast, the variable C has a different element set for each value of i, and these assignments do affect the variable C in the context of the parfor statement.

Another important use of parfor has the following form:

s = 0;
parfor i = 1:n
   if p(i)   % assume p is a function
      s = s + 1;
   end
end

The key point of this example is that the conditional adding of 1 to s can be done in any order. After the parfor statement has finished executing, the value of s depends only on the number of iterations for which p(i) is true. As long as p(i) depends only upon i, the value of s is deterministic. This technique generalizes to functions other than plus (+).

Note that the variable s refers to the variable in the context of the parfor statement. The general rule is that the only variables in the context of a parfor statement that can be affected by it are those like s (combined by a suitable function like +) or those like C in the previous example (set by indexed assignment).

See Also

for | numlabs | parallel.pool.Constant | parpool | pmode