Future

Function scheduled to run

Description

A Future object represents a function that you schedule to run in MATLAB^®.

• If you use parfeval or parfevalOnAll to create a Future, MATLAB runs the function:

  • In the background, if you specify backgroundPool when creating the Future.

  • On a parallel pool, if you do not specify backgroundPool when creating the Future, have Parallel Computing Toolbox™ and one of the following applies:

    • You have a parallel pool currently open.

    • You have automatic pool creation enabled.

  • In serial, otherwise.

• If you use afterEach or afterAll to create a Future, the function is run by your current MATLAB session. It is not run in the background or on any parallel pool.

Creation

You create a Future object when you do one of the following:

• Use parfeval to schedule a function to run in the background, on a parallel pool, or in serial.

• Use parfevalOnAll to schedule a function to run on all workers in a pool, or in serial.

• Use afterEach or afterAll to schedule a function to run after Future objects finish.

The available types of future objects follow.

Future Object	Description
FevalFuture	Created by parfeval
FevalOnAllFuture	Created by parfevalOnAll
AfterEachFuture	Created by afterEach
AfterAllFuture	Created by afterAll

Properties

General Options

CreateDateTime — Date and time when Future was created

datetime scalar

This property is read-only.

Date and time when the Future object was created, specified as a datetime scalar.

Error — Error information

exception scalar | cell array

This property is read-only.

Error information, specified as an MException scalar or cell array of exception objects.

• If you create a Future object using parfeval or afterAll, this property is a cell array or exception scalar. If the Future object completes with no error, this property is empty.

• If you create a Future object using afterEach, this property is a cell array with one cell for each execution of the Future that errored, or a 1-by-1 cell array if the Future was canceled. If the Future object completes with no error, this property is empty.

• If you create a Future object using parfevalOnAll, this property is a cell array with one cell for each worker if any errors occurred on the workers, or a 1-by-1 cell array if the Future was canceled. If the Future object completes with no error, this property is empty.

For more information about errors encountered when you schedule a function to run after Future objects finish, see afterEach and afterAll.

FinishDateTime — Date and time when function finished

datetime scalar

This property is read-only.

Date and time when the function finished, specified as a datetime scalar.

The Future finishes running when MATLAB finishes running the function associated with it.

If the function associated with the Future object is not finished running, this property is an empty datetime array.

Data Types: datetime

Function — Function associated with Future

function_handle

This property is read-only.

Function associated with the Future object, specified as a function handle.

• If you create the Future using parfeval or parfevalOnAll, MATLAB runs the function in the background, on a parallel pool (if you have Parallel Computing Toolbox), or in serial.

• If you create the Future using afterEach or afterAll, the function is run by your current MATLAB session. It is not run in the background or on any parallel pool.

Example: @magic

Data Types: function_handle

ID — Identifier

integer scalar

This property is read-only.

Identifier, specified as an integer scalar.

Data Types: double

InputArguments — Input arguments for function

cell array

This property is read-only.

Input arguments for the function, specified as a cell array.

When the scheduled function fcn specified by the Function property runs, it runs as fcn(X{:}), where X is the cell array of input arguments specified by this property.

Example: {[1]}

Example: {[1,2], [2,1]}

Data Types: cell

NumOutputArguments — Number of arguments returned by function

integer scalar

This property is read-only.

Number of arguments returned by the function, specified as an integer scalar.

The function specified by the Function property must return at least as many arguments as specified by this property.

Data Types: double

OutputArguments — Output arguments from running function

cell array

This property is read-only.

Output arguments from running the function, specified as a cell array.

This property is an empty cell array if the Future object is not finished running or the Future object completes with an error.

Example: {[3.14]}

Data Types: cell

RunningDuration — Current duration of Future

duration scalar

Current duration of the Future object, specified as a duration scalar.

When the Future object finishes running, this property becomes constant.

StartDateTime — Date and time when Future started running

datetime scalar

This property is read-only.

Date and time when the Future object started running, specified as a datetime scalar.

The Future starts running when MATLAB starts running the function associated with it.

Data Types: datetime

State — Current state of future

'queued' | 'running' | 'finished' | 'failed' | 'unavailable'

This property is read-only.

Current state of the future, specified as one of these values:

• 'queued' — Future is queued, and the function associated with it is scheduled to run.

• 'running' — Function associated with the Future is currently running.

• 'finished' or 'failed' — Function associated with the Future is finished running.

• 'unavailable' — Future is unable to run. Elements of a preallocated Future array have this state.

FevalFuture Options

Diary — text output

character vector

This property is read-only.

Text output, specified as a character vector.

This property is a character vector containing all text that is displayed if you explicitly run the functions specified by the Function property using the input arguments specified by the InputArguments property.

Parent — Queue of Future objects

parallel.FevalQueue object

This property is read-only.

Queue of Future objects, specified as a parallel.FevalQueue object.

This property is equal to the queue of Future objects given by the FevalQueue of the pool that the future is running on.

This property is not available for Future objects that run functions in a thread-based environment.

Read — Flag indicating if outputs have been read

true | false

This property is read-only.

Flag indicating if outputs have been read, specified as true or false.

This property is set to true only if you use fetchOutputs or fetchNext.

Data Types: logical

FevalOnAllFuture Options

Diary — Text produced by execution of function

cell array of character vectors

This property is read-only.

Recorded text, specified as a cell array of character vectors.

This property is a cell array containing all text that is displayed if you explicitly run the functions specified by the Function property using the input arguments specified by the InputArguments property.

The j^th element of the array is the text output captured from the j^th worker in the pool that ran the Future.

Data Types: cell

Parent — Queue of Future objects

parallel.FevalQueue object

This property is read-only.

Queue of Future objects, specified as a parallel.FevalQueue object.

This property is equal to the queue of Future objects given by the FevalQueue of the pool that the future is running on.

This property is not available for Future objects that run functions in a thread-based environment.

Object Functions

General Functions

afterAll	Run function after all functions finish running in the background
afterEach	Run function after each function finishes running in the background
cancel	Stop function running in the background
fetchOutputs	Retrieve results from function running in the background
wait	Wait for futures to complete

FevalFuture Only

fetchNext

Retrieve next unread outputs from Future array

Examples

Run Callback Function After Function Finishes Running in the Background

This example shows how to use afterEach to schedule a callback function to run after a function finishes running in the background.

Use parfeval to run the function rand(1) and retrieve one output. Specify backgroundPool as the first argument to run the function in the background. Repeat 10 times to create 10 Future objects.

for i = 1:10
    f(i) = parfeval(backgroundPool,@rand, 1, 1);
end

After each Future finishes, display the value using the disp function. The input arguments for disp are the output arguments from each Future. Specify the third argument to the afterEach function as 0 to return no outputs from the callback.

afterEach(f,@disp,0);

Update Wait Bar While Functions Run in the Background

This example shows how to use afterEach to update a wait bar with the progress of functions running in the background.

Create a wait bar, w.

w = waitbar(0,'Please wait ...');

Set the number of iterations for your for-loop, N. Store the current number of completed iterations, 0, and the total number of iterations, N, in the UserData property of the wait bar.

N = 20;
w.UserData = [0 N];

Run a for-loop with N iterations. In each iteration, use parfeval and backgroundPool to run pause in the background for a random number of seconds. Store each Future object in an array.

for i = 1:N
    delay = rand;
    f(i) = parfeval(backgroundPool,@pause,0,delay);
end

Use the helper function updateWaitbar to update the waitbar after each Future finishes.

afterEach(f,@(~)updateWaitbar(w),0);

Use delete to close the wait bar after all the Future objects finish.

afterAll(f,@(~)delete(w),0);

Define Helper Function

Define the helper function updateWaitbar. The function increments the first element of the UserData property, then uses the vector to calculate the progress.

function updateWaitbar(w)
    % Update a waitbar using the UserData property.

    % Check if the waitbar is a reference to a deleted object
    if isvalid(w)
        % Increment the number of completed iterations 
        w.UserData(1) = w.UserData(1) + 1;

        % Calculate the progress
        progress = w.UserData(1) / w.UserData(2);

        % Update the waitbar
        waitbar(progress,w);
    end
end

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.

Tips

• Future objects are local objects and can be accessed only in the MATLAB session that created them.

  For example, if you use parfeval to run a function in the background and create a Future object, the Future is not available in the workspace of background workers.

Extended Capabilities

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