parfeval

Run function in background

Since R2021b

Syntax

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

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

Description

F = parfeval(backgroundPool,fcn,numFcnOut,X1,...,Xm) schedules the function fcn to run in the background. You can run other code while MATLAB^® is running the function fcn.

To run a function on a parallel pool, see parfeval (Parallel Computing Toolbox).

parfeval runs the function fcn on a background worker. For more information about workers and the background, see Background Workers.

MATLAB asynchronously evaluates the function fcn on each worker with X1,X2,…,Xm input arguments 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.

F = parfeval(fcn,numFcnOut,X1,...,Xm) schedules the function fcn to be run.

MATLAB returns the Future object F before the function fcn finishes running.

Use this syntax in code designed for use with Parallel Computing Toolbox™.

• If you do not have Parallel Computing Toolbox, you do not use any parallel resources. The function runs in serial.

• If you have Parallel Computing Toolbox, parfeval automatically uses parallel resources.

Examples

Run Functions in Background

This example shows how to run a function in the background using parfeval and backgroundPool. When you run a function in the background, you can run other MATLAB® code at the same time.

Use parfeval to run the function magic(3) and retrieve one output. Specify backgroundPool as the first argument to run the function in the background. When you use parfeval, you create a Future object.

f = parfeval(backgroundPool,@magic,1,3);

To retrieve the output from the background, use fetchOutputs. MATLAB returns the output once the execution of magic is complete.

fetchOutputs(f)

ans = 3×3

     8     1     6
     3     5     7
     4     9     2

Stop Functions Running in Background

This example shows how to stop a MATLAB function that you are running in the background. When you use parfeval to run a function in the background, MATLAB immediately returns a Future object. Long-running functions can block other functions from running in the background. To stop the function from running, you must use the cancel function instead of selecting Live Editor > Run > Stop.

Use parfeval to run pause(Inf) without retrieving any outputs. Specify backgroundPool as the first argument to run the function in the background. When you use parfeval, you create a Future object.

f = parfeval(backgroundPool,@pause,0,Inf);

Check the state of the Future object.

f.State

ans = 
'running'

When you run parfeval, you schedule a function to run in the background. When the background pool has insufficient resources to run the function, the Future is in the 'queued' state. When the function is run by the background pool, the Future is in the 'running' state.

To stop the function from running in the background, cancel the Future object.

cancel(f)
f.State

ans = 
'finished'

The function is now in the 'finished' state.

Input Arguments

fcn — Function to run

function handle

Function to run, specified as a function handle.

Example: fcn = @magic

numFcnOut — Number of output arguments requested

nonnegative integer scalar

Number of output arguments requested from function fcn, specified as an nonnegative integer scalar.

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.

Output Arguments

F — Output Future

parallel.Future object

Output Future, returned as a parallel.Future object.

• Use fetchOutputs or fetchNext to retrieve results from F.

• Use afterEach or afterAll to run a function when F completes.

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 (Parallel Computing Toolbox).

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 R2021b