Main Content

parfeval

Run function in background

collapse all in page

    Syntax

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

    Description

    example

    F = parfeval(backgroundPool,fcn,n,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 evaluates the function fcn asynchronously as [Y1,...,Yn] = fcn(X1,...,Xm), with m inputs and n outputs.

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

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

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

    Use this syntax to run 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

    collapse all

    Open Live Script

    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
    Open Live Script

    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

    collapse all

    Function to run, specified as a function handle.

    Example: fcn = @magic

    Number of output arguments, specified as an nonnegative integer scalar.

    n is the number of output arguments expected from running 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.

    Output Arguments

    collapse all

    Output Future, returned as a parallel.Future object.

    Extended Capabilities

    See Also

    | (Parallel Computing Toolbox) | | | | | | |

    Topics