Execute loop iterations in parallel
parfor loopvar = initval:endval, statements, end
parfor (loopvar = initval:endval, M), statements, end
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
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.
|Invalid parfor Range||Reason Range Not Valid|
|The resulting range,|
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,
M to specify the maximum number
of MATLAB® workers that will evaluate statements in the body of
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.
parfor-loop cannot run on workers
in a parallel pool (for example, if no workers are available or
0), MATLAB executes
the loop on the client in a serial manner. In this situation, the
are preserved in that the loop iterations can execute in any order.
Because of independence of iteration order, execution of
Do not use
The maximum amount of data that can be transferred in a single
chunk between client and workers in the execution of a
is determined by the JVM™ memory allocation limit. For details,
see Attached Files Size Limitations.
For a detailed description of
see Parallel for-Loops (parfor).
f is a time-consuming function
to compute, and that you want to compute its value on each element
A and place the corresponding results
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
Next assume that
C are variables and that
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
h is large,
be significantly faster than the corresponding
n is relatively small. Although the form
of this statement is similar to a
the behavior can be significantly different. Notably, the assignments
to the variables
u do not affect
variables with the same name in the context of the
The rationale is that the body of the
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
By contrast, the variable
C has a different element
set for each value of
i, and these assignments do affect
C in the context of the
Another important use of
parfor has the following
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
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
As long as
p(i) depends only upon
the value of
s is deterministic. This technique
generalizes to functions other than
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
that can be affected by it are those like
by a suitable function like
+) or those like
the previous example (set by indexed assignment).
When an error occurs during the execution of a
all iterations that are in progress are terminated, new ones are not
initiated, and the loop terminates.
Errors and warnings produced on workers are annotated with the worker ID and displayed in the client's Command Window in the order in which they are received by the client MATLAB.
Do not use
the end of the
parfor-loop, if it is used within
the loop body.
parfor-loop runs on the existing
parallel pool. If no pool exists,
parfor will start
a new parallel pool, unless the automatic starting of pools is disabled
in your parallel preferences. If there is no parallel pool and
start one, the loop runs serially in the client session.
parfor-loop, the functions
always return a value of 1.
in the cluster profile for the parallel pool is set to
MATLAB performs an analysis on a
to determine what code files are necessary for its execution, then
automatically attaches those files to the parallel pool so that the
code is available to the workers.