Main Content

parfeval

Run function on parallel pool worker

Description

example

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.

example

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

collapse all

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.

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
      ⋮

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 preferences, 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

collapse all

Function to run on a worker, specified as a function handle.

Example: fcn = @sum

Data Types: function_handle

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

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

Pool, specified as a parallel.Pool object.

Example: parpool("Processes");

Example: backgroundPool;

Output Arguments

collapse all

Future, returned as a parallel.FevalFuture object.

Extended Capabilities

Version History

Introduced in R2013b

expand all