parfeval

Run function on parallel pool worker

Syntax

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

F = parfeval(pool,fcn,numFcnOut,X1,...,Xm)

Description

F = parfeval(fcn,numFcnOut,X1,...,Xm) schedules the function fcn to be run. MATLAB^® runs the function using a parallel pool if one is available. Otherwise, it runs the function in serial.

You can share your parallel code that uses this syntax with MATLAB users who do not have Parallel Computing Toolbox™.

MATLAB asynchronously evaluates the function fcn on each worker with the specified input arguments X1,…Xm, and returns numFcnOut output arguments.

MATLAB returns the Future object F before the function fcn finishes running. You can use fetchOutputs to retrieve the results from the future. To stop running the function fcn, use the cancel function. For more information about futures, see Future.

If a parallel pool is open, MATLAB uses that parallel pool to run the function fcn.

If a parallel pool is not open, the behavior depends on whether automatic pool creation is enabled.

• Automatic pool creation is enabled — MATLAB starts a parallel pool using the default cluster profile, then uses that parallel pool to run the function fcn. Automatic pool creation is enabled by default.

  You can manually force this behavior by specifying parpool to the pool argument pool.

• Automatic pool creation is disabled — MATLAB runs the function fcn using deferred execution.

  You can manually force this behavior by specifying parallel.Pool.empty to the pool argument pool.

F = parfeval(pool,fcn,numFcnOut,X1,...,Xm) schedules the function fcn to run using the pool pool. Use this syntax when you want to specify a pool at runtime.

To run code in the background, see the MATLAB function page parfeval.

Examples

Execute Function Asynchronously and Fetch Outputs

Use parfeval to request asynchronous execution of a function on a worker.

Submit a single request to the parallel pool. Retrieve the outputs by using the fetchOutputs function.

f = parfeval(@magic,1,10);

Starting parallel pool (parpool) using the 'Processes' profile ...
Connected to parallel pool with 6 workers.

value = fetchOutputs(f);
value(1)

ans = 92

Specify multiple future requests in a for-loop, and collect the results in a vector as they become available. For efficiency, preallocate an array of future objects before you start the loop.

f(1:10) = parallel.FevalFuture;
for idx = 1:10
    f(idx) = parfeval(@magic,1,idx);
end

Retrieve the individual future outputs as they become available by using fetchNext. If no element of the FevalFuture object array is available when you call fetchNext, MATLAB waits until an element becomes available.

magicResults = cell(1,10);
for idx = 1:10
    [completedIdx,value] = fetchNext(f);
    magicResults{completedIdx} = value;
    fprintf("Got result with index: %d.\n",completedIdx)
end

Got result with index: 1.
Got result with index: 2.
Got result with index: 3.
Got result with index: 7.
Got result with index: 8.
Got result with index: 9.
Got result with index: 10.
Got result with index: 4.
Got result with index: 5.
Got result with index: 6.

Execute Function on Specific Parallel Pool

Start a parallel pool using the remote cluster profile myMJSCluster.

myClusterPool = parpool(myMJSCluster,15);

Starting parallel pool (parpool) using the 'myMJSCluster' profile ...
Connected to parallel pool with 15 workers.

Use parfeval to compute the sum of the elements in each column of a 1000-by-1000 matrix on the pool myClusterPool. Retrieve the results.

f = parfeval(myClusterPool,@sum,1,rand(1000));
results = fetchOutputs(f)'

results = 1000×1

  509.8296
  483.2762
  505.1542
  479.3408
  489.2463
  512.2336
  495.8580
  499.5442
  487.5374
  491.4364
      ⋮

Update User Interface Asynchronously Using afterEach and afterAll

This example shows how to update a user interface as computations complete. When you offload computations to workers using parfeval, all user interfaces are responsive while workers perform the computations. You can use waitbar to create a simple user interface.

• Use afterEach to update the user interface after each computation completes.

• Use afterAll to update the user interface after all the computations complete.

Use waitbar to create a figure handle, h. When you use afterEach or afterAll, the waitbar function updates the figure handle. For more information about handle objects, see Handle Object Behavior.

h = waitbar(0,'Waiting...');

Use parfeval to calculate the real part of the eigenvalues of random matrices. With default settings, parfeval creates a parallel pool automatically if one has not already been created. For efficiency, preallocate an array of Future objects.

f(1:100) = parallel.FevalFuture;
for idx = 1:100
    f(idx) = parfeval(@(n) real(eig(randn(n))),1,5e2); 
end

You can use afterEach to automatically invoke functions on each of the results of the parfeval computations. Use afterEach to schedule another set of future objects to compute the largest value in each of the output arrays after each future in the f completes.

maxFuture = afterEach(f,@max,1);

You can use the State property to obtain the status of futures. Define an anonymous function that updates the fractional wait bar length of h to the fraction of Future objects that have finished executing. The updateWaitbar anonymous function computes the mean of a logical array in which an element is true if the State property of the corresponding Future object in f is "finished".

updateWaitbar = @(~) waitbar(mean({f.State} == "finished"),h);

Use afterEach and updateWaitbar to update the fractional wait bar length after each future in maxFuture completes. Use afterAll and delete to close the wait bar after all the computations are complete.

updateWaitbarFutures = afterEach(f,updateWaitbar,0);
afterAll(updateWaitbarFutures,@(~) delete(h),0)

Use afterAll and histogram to show a histogram of the results in maxFuture after all the futures complete.

showsHistogramFuture = afterAll(maxFuture,@histogram,0);

Input Arguments

fcn — Function to run on worker

function handle

Function to run on a worker, 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.

numFcnOut is the number of output arguments you request when you run fcn(X1,...,Xm).

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.

pool — Pool

parallel.Pool object

Pool, specified as a parallel.Pool object.

• To create a parallel pool, use parpool.

• To get the background pool, use backgroundPool.

Example: parpool("Processes");

Example: backgroundPool;

Output Arguments

F — Future

parallel.FevalFuture object

Future, returned as a parallel.FevalFuture object.

• Use fetchOutputs or fetchNext to retrieve results from F.

• Use afterEach or afterAll to run a function when F completes a computation or all computations, respectively.

Extended Capabilities

Automatic Parallel Support

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

Usage notes and limitations:

• The syntax parfeval(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: parfeval can now run in serial with no pool

Starting in R2021b, you can now run parfeval 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 parfeval(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.