Parallel Computing Toolbox™

Programming Considerations

MATLAB^® Path

All workers executing a parfor-loop must have the same MATLAB^® path configuration as the client, so that they can execute any functions called in the body of the loop. Therefore, whenever you use cd, addpath, or rmpath on the client, it also executes on all the workers, if possible. For more information, see the matlabpool reference page. When the workers are running on a different platform than the client, use the function pctRunOnAll to properly set the MATLAB path on all workers.

Back to Top

Error Handling

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.

The behavior of lastwarn and lasterror are unspecified at the end of the parfor if they are used within the loop body.

Back to Top

Limitations

Unambiguous Variable Names

You cannot have names in a parfor-loop that are ambiguous as to whether they refer to a variable or function at the time the code is read. (See Naming Variables in the MATLAB documentation.) For example, in the following code, if f is not a function on the path when the code is read, nor clearly defined as a variable in the code, f(5) could refer either to the fifth element of the array f, or to the function f with an argument of 5.

parfor i=1:n
   ...
   a = f(5);
   ...
end

Transparency

The body of a parfor-loop must be transparent, meaning that all references to variables must be "visible" (i.e., they occur in the text of the program).

In the following example, because X is not visible as an input variable in the parfor body (only the string 'X' is passed to eval), it does not get transferred to the workers. As a result, MATLAB issues an error at run time:

X = 5;
parfor i = 1:4
    eval('X');
end

Other functions that violate transparency are evalc, evalin, and assignin with the workspace argument specified as 'caller'; save and load, unless the output of load is assigned.

MATLAB does successfully execute eval and evalc statements that appear in functions called from the parfor body.

Nondistributable Functions

If you use a function that is not strictly computational in nature (e.g., input, plot, keyboard) in a parfor-loop or in any function called by a parfor-loop, the behavior of that function occurs on the worker. The results might include hanging the worker process or having no visible effect at all.

Nested Functions

The body of a parfor-loop cannot make reference to a nested function. However, it can call a nested function by means of a function handle.

Nested parfor-Loops

The body of a parfor-loop cannot contain another parfor-loop. However, it can call a function that contains another parfor-loop.

Break and Return Statements

The body of a parfor-loop cannot contain break or return statements.

Global and Persistent Variables

The body of a parfor-loop cannot contain global or persistent variable declarations.

Back to Top

Performance Considerations

Slicing Arrays

If a variable is initialized before a parfor-loop, then used inside the parfor-loop, it has to be passed to each MATLAB worker evaluating the loop iterations. Only those variables used inside the loop are passed from the client workspace. However, if all occurrences of the variable are indexed by the loop variable, each worker receives only the part of the array it needs. For more information, see Where to Create Arrays.

Local vs. Cluster Workers

Running your code on local workers might offer the convenience of testing your application without requiring the use of cluster resources. However, there are certain drawbacks or limitations with using local workers. Because the transfer of data does not occur over the network, transfer behavior on local workers might not be indicative of how it will typically occur over a network. For more details, see Optimizing on Local vs. Cluster Workers.

Back to Top

Compatibility with Earlier Versions of MATLAB^® Software

In versions of MATLAB prior to 7.5 (R2007b), the keyword parfor designated a more limited style of parallel for-loop than what is available in MATLAB 7.5 and later. This old style was intended for use with distributed arrays inside a parallel job, and has been replaced by a for-loop that uses drange to define its range; see Using a for-Loop Over a Distributed Range (for-drange).

The past and current functionality of the parfor keyword is outlined in the following table:

parfor i = range
  loop body
    .
    .
end

for i = drange(range)
  loop body
    .
    .
end

parfor i = range
  loop body
    .
    .
end

Back to Top

Getting Started with parfor

Advanced Topics