Future

Request function execution on parallel pool workers or MATLAB client

expand all in page

Description

A Future object represents a function to be executed on parallel pool workers or the MATLAB® client.

Creation

There are several ways to create a Future object:

  • Specify a function to be executed on a worker in a parallel pool using parfeval. The parfeval function creates a FevalFuture object to represent the function execution and hold the results. To create multiple FevalFutures, call parfeval multiple times; for example, you can create a vector of FevalFutures in a for-loop.

  • Specify a function to be executed on every worker in a parallel pool using parfevalOnAll. The parfevalOnAll function creates a FevalOnAllFuture object to represent the function execution and hold the results.

  • Specify a function to be executed on the MATLAB client after all Future objects complete using afterAll. The afterAll function creates an AfterAllFuture object to represent the function execution and hold the results.

  • Specify a function to be executed on the MATLAB client after each Future object complete using afterEach. The afterEach function creates an AfterEachFuture object to represent the function execution and hold the results.

In summary, the following table describes the available types of future objects:

Future ObjectDescription
FevalFutureSingle parfeval Future instance
FevalOnAllFutureparfevalOnAll Future instance
AfterAllFutureafterAll Future instance
AfterEachFutureafterEach Future instance

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

Properties

expand all

General Options

This property is read-only.

Date and time when this future was created, specified as a datetime object.

Data Types: datetime

This property is read-only.

Error information, specified as an exception. If the Future completes with no error, then this field is empty.

This property is read-only.

Date and time when this future finished running, specified as a datetime object.

Data Types: datetime

This property is read-only.

Function to evaluate, specified as a function handle.

Example: @rand

Data Types: function_handle

This property is read-only.

Numeric identifier for the future, specified as an integer.

Data Types: double

This property is read-only.

Input arguments to the function to execute, specified as a cell array.

Example: {[1]}

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

Data Types: cell

This property is read-only.

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

Data Types: double

This property is read-only.

Output arguments, specified as a cell array of results from the running function after it finishes execution. If the Future completes with errors, this field is empty. To see the error, check the Error property.

Example: {[3.14]}

Data Types: cell

This property is read-only.

Date and time when this future started running, specified as a datetime object.

Data Types: datetime

This property is read-only.

Current state of the future, specified as one of these values: 'pending', 'queued', 'running', 'finished', 'failed', or 'unavailable'.

Data Types: char

FevalFuture Options

This property is read-only.

Text produced by execution of function, specified as a char array.

Data Types: char

This property is read-only.

Queue of Future objects that contains this Future, specified as a FevalQueue. Check this queue to identify the number of Future objects running or queued.

Data Types: FevalQueue

This property is read-only.

Indication if outputs have been read by fetchNext or fetchOutputs, specified as a logical.

Data Types: logical

FevalOnAllFuture Options

This property is read-only.

Text produced by execution of the function, specified as a cell array of character arrays that contains the text for each worker.

Data Types: cell

This property is read-only.

Queue of Future objects that contains this Future, specified as a FevalQueue. Check this queue to identify the number of Future objects running or queued.

Data Types: FevalQueue

Object Functions

expand all

afterAllSpecify a function to invoke after all parallel.Futures complete
afterEachSpecify a function to invoke after each parallel.Future completes
cancelCancel queued or running future
fetchOutputsRetrieve all output arguments from Future
isequalTrue if futures have same ID
waitWait for futures to complete
fetchNextRetrieve next available unread FevalFuture outputs

Examples

collapse all

Open Live Script

You can combine afterEach and afterAll to automatically invoke more functions on the results of futures. Both afterEach and afterAll generate future variables that can be used again in afterEach and afterAll.

Use parfeval to compute random vectors in the workers. With default preferences, parfeval creates a parpool automatically if there is not one already created.

for idx= 1:10
    f(idx) = parfeval(@rand, 1, 1000, 1);
end
Starting parallel pool (parpool) using the 'local' profile ...
connected to 8 workers.

Compute the largest element in each of those vectors when they become ready. afterEach executes the function handle on the output of each future when they become ready and creates another future to hold the results. 

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

To compute the minimum value among them, call afterAll on this new future. afterAll executes a function on the combined output arguments of all the futures after they all complete. In this case, afterAll executes the function min on the outputs of maxFuture after completing and creates another future to hold the result.

minFuture = afterAll(maxFuture, @(r) min(r), 1);

You can fetch the result using fetchOutputs. fetchOutput waits until the future completes to gather the results.

fetchOutputs(minFuture)
ans = 0.9973

You can check the result of afterEach by calling fetchOutputs on its future variable. 

fetchOutputs(maxFuture)
ans = 10×1

    0.9996
    0.9989
    0.9994
    0.9973
    1.0000
    1.0000
    0.9989
    0.9994
    0.9998
    0.9999

See Also

| | | |

Introduced in R2013b

Parallel Computing Toolbox Documentation

Support