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
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.
Invalid parfor Range | Reason Range Not Valid |
---|---|
parfor i = 1:2:25 | 1, 3, 5,... are not consecutive. |
parfor i = -7.5:7.5 | -7.5, -6.5,... are not integers. |
| The resulting range, 1, 2, 4,... , has nonconsecutive
integers. |
parfor i = [5;6;7;8] | [5;6;7;8] is a column vector, not a row
vector. |
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 |
Note
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 parfor
-loop
is determined by the JVM™ memory allocation limit. For details,
see Attached Files Size Limitations.
For a detailed description of parfor
-loops,
see Parallel for-Loops (parfor).
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).
When an error occurs during the execution of a parfor
-loop,
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 lastwarn
at
the end of the parfor
-loop, if it is used within
the loop body.