parfevalOnAll

Run function asynchronously on all workers in parallel pool

Syntax

F = parfevalOnAll(p,fcn,numFcnOut,X1,...,Xm)

F = parfevalOnAll(fcn,numFcnOut,X1,...,Xm)

Description

F = parfevalOnAll(p,fcn,numFcnOut,X1,...,Xm) requests the asynchronous execution of the function fcn on all workers in the parallel pool p. The parfevalOnAll function evaluates fcn on each worker with input arguments X1,...,Xm and returns numFcnOut output arguments. You can obtain the results from the Future object F when all workers have completed running fcn.

F = parfevalOnAll(fcn,numFcnOut,X1,...,Xm) requests asynchronous execution on all workers in the current parallel pool. If no pool exists, and automatic pool creation is enabled, MATLAB^® starts a new parallel pool.

Note

Use parfevalOnAll instead of parfor or spmd if you want to use clear. This preserves workspace transparency. See Ensure Transparency in parfor-Loops or spmd Statements.

Examples

Run Functions on All Workers

You can use the parfevalOnAll function to run a clean up function on all the workers while preserving workspace transparency.

For example. to unload a mex file before deleting temporary folders for distributing simulations, run the clear function on all the workers using parfevalOnAll. Because clear has 0 output arguments, specify 0 to the numFcnOut input argument of parfevalOnAll.

parfevalOnAll(@clear,0,"mex");

To close all Simulink model windows on all the workers, run the bdclose using the parfevalOnAll function.

p = gcp; % Get the current parallel pool
f = parfevalOnAll(p,@bdclose,0,"all");

In both cases, wait for completion and verify success by using the fetchOutputs function. Even when you do not request output arguments, you can use fetchOutputs on the future to check for errors from the workers.

fetchOutputs(f)

Input Arguments

p — Parallel pool

parallel.Pool object

Parallel pool of workers, specified as a parallel.Pool object. You can create a parallel pool by using the parpool function.

fcn — Function to run on workers

function handle

Function to run on the workers, specified as a function handle.

Example: fcn = @sum

Data Types: function_handle

numFcnOut — Number of output arguments requested

nonnegative integer

Number of output arguments requested from the function fcn, specified as a nonnegative integer.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

X1,...,Xm — Input arguments

comma-separated list of variables or expressions

Input arguments, specified as a comma-separated list of variables or expressions. The parallel pool worker inputs these arguments to the function fcn.

Output Arguments

F — Future

parallel.FevalOnAllFuture object

Future, returned as a parallel.FevalOnAllFuture object, that represents the execution of fcn on all the parallel workers and holds their results. Use fetchOutputs to collect the results.

Extended Capabilities

Automatic Parallel Support

Accelerate code by automatically running computation in parallel using Parallel Computing Toolbox™.

Usage notes and limitations:

• The syntax parfevalOnAll(fcn,numFcnOut,X1,...,Xm) has automatic parallel support if you have Parallel Computing Toolbox™.

For more information, see Run MATLAB Functions with Automatic Parallel Support.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2013b

R2021b: parfevalOnAll can now run in serial with no pool

Starting in R2021b, you can now run parfevalOnAll in serial with no pool. This behavior allows you to share parallel code that you write with users who do not have Parallel Computing Toolbox.

When you use the syntax parfevalOnAll(fcn,numFcnOut,X1,...,Xm), MATLAB tries to use an open parallel pool if you have Parallel Computing Toolbox. If a parallel pool is not open, MATLAB will create one if automatic pool creation is enabled.

If parallel pool creation is disabled or if you do not have Parallel Computing Toolbox, the function is evaluated in serial. In previous releases, MATLAB threw an error instead.